---
title: "Analyze a domain"
method: POST
path: "/projects/{project_id}/domain-overview/analyze"
tags: ["domain-overview"]
---

# Analyze a domain

`POST /projects/{project_id}/domain-overview/analyze`

## Request

- Base URL: `https://eu.bisibility.com/api/v1`
- URL: `https://eu.bisibility.com/api/v1/projects/{project_id}/domain-overview/analyze`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `/api/auth/oauth2/authorize`, token URL `/api/auth/oauth2/token`, scopes: `api:write`)

estimate_only is a free cache-aware dry run. estimate_only=true needs only read scope and never spends provider budget. Paid analysis requires an explicit max_cost_cents, including zero for cache-only access. Charged partial reports return HTTP 200 with nested module failures and their costs.

## Path parameters

- `project_id` string, required: Public project ID; membership and token scope are enforced.

## Headers

- `Bisibility-API-Version` 'v1'
- `Idempotency-Key` string
- `X-Bisibility-Source` 'sdk' | 'cli' | 'mcp'

## Request body

- union
  - object
    - `estimate_only` true, required
    - `fresh` boolean
    - `language_code` string, required
    - `location_code` integer, required
    - `scope_override` 'root' | 'subdomain'
    - `target` string, required
    - `keyword_limit` integer
    - `max_cost_cents` integer: Required for paid analysis; estimate_only may omit it.
    - `page_limit` integer
  - object
    - `estimate_only` false
    - `fresh` boolean
    - `language_code` string, required
    - `location_code` integer, required
    - `scope_override` 'root' | 'subdomain'
    - `target` string, required
    - `keyword_limit` integer
    - `max_cost_cents` integer, required: Required for paid analysis; estimate_only may omit it.
    - `page_limit` integer

## Response `200`

JSON response

- DomainOverviewAnalyzeResponse
  - `data` union, required
    - object
      - `cached` boolean, required
      - `estimate` true, required
      - `estimated_cost_cents` number, required
      - `fresh_estimated_cost_cents` number, required
      - `history_estimated_cost_cents` number, required
      - `history_mode` 'lazy', required
      - `keyword_limit` integer: Requested page size, echoed from the analyze request.
      - `keyword_page_estimated_cost_cents` number, required
      - `language_code` string, required
      - `location_code` integer, required
      - `page_limit` integer: Requested page size, echoed from the analyze request.
      - `page_page_estimated_cost_cents` number, required
      - `provider` string, required
      - `scope` 'root' | 'subdomain', required
      - `target` string, required
    - object
      - `cached` boolean, required
      - `cached_until` string, date-time, required
      - `cost_cents` number, required
      - `fetched_at` string, date-time, required
      - `history_mode` 'lazy', required
      - `keyword_limit` integer: Requested page size, echoed from the analyze request.
      - `keywords` union, required
        - object
          - `cached` boolean, required
          - `cost_cents` number, required
          - `data` DomainOverviewKeywordsData, required
            - `cost_cents` number, required
            - `rows` object[], required
              - …
            - `total_count` integer, nullable, required
          - `fetched_at` string, date-time, nullable, required
          - `ok` true, required
        - object
          - `cost_cents` number, required
          - `ok` false, required
          - `reason` 'budget_exhausted' | 'cost_limit_exceeded' | 'in_progress' | 'lookup_failed' | 'needs_reauth' | 'no_source' | 'rate_limited' | 'snapshot_expired' | 'unsupported_location', required
          - `reset_at` number
      - `language_code` string, required
      - `location_code` integer, required
      - `overview` DomainOverviewMetrics, required
        - `count` integer, nullable, required
        - `estimated_traffic_cost_cents` number, nullable, required
        - `etv` number, nullable, required
        - `is_down` integer, required
        - `is_lost` integer, required
        - `is_new` integer, required
        - `is_up` integer, required
        - `pos1` integer, required
        - `pos2_3` integer, required
        - `pos4_10` integer, required
        - `pos11_20` integer, required
        - `pos21_30` integer, required
        - `pos31_40` integer, required
        - `pos41_50` integer, required
        - `pos51_60` integer, required
        - `pos61_70` integer, required
        - `pos71_80` integer, required
        - `pos81_90` integer, required
        - `pos91_100` integer, required
      - `page_limit` integer: Requested page size, echoed from the analyze request.
      - `pages` union, required
        - object
          - `cached` boolean, required
          - `cost_cents` number, required
          - `data` DomainOverviewPagesData, required
            - `cost_cents` number, required
            - `rows` object[], required
              - …
            - `total_count` integer, required
          - `fetched_at` string, date-time, nullable, required
          - `ok` true, required
        - object
          - `cost_cents` number, required
          - `ok` false, required
          - `reason` 'budget_exhausted' | 'cost_limit_exceeded' | 'in_progress' | 'lookup_failed' | 'needs_reauth' | 'no_source' | 'rate_limited' | 'snapshot_expired' | 'unsupported_location', required
          - `reset_at` number
      - `previous_fetched_at` string, date-time, nullable, required
      - `previous_overview` DomainOverviewMetrics, required
        - `count` integer, nullable, required
        - `estimated_traffic_cost_cents` number, nullable, required
        - `etv` number, nullable, required
        - `is_down` integer, required
        - `is_lost` integer, required
        - `is_new` integer, required
        - `is_up` integer, required
        - `pos1` integer, required
        - `pos2_3` integer, required
        - `pos4_10` integer, required
        - `pos11_20` integer, required
        - `pos21_30` integer, required
        - `pos31_40` integer, required
        - `pos41_50` integer, required
        - `pos51_60` integer, required
        - `pos61_70` integer, required
        - `pos71_80` integer, required
        - `pos81_90` integer, required
        - `pos91_100` integer, required
      - `previous_source_snapshot_at` string, date-time, nullable, required
      - `provider` string, required
      - `scope` 'root' | 'subdomain', required
      - `source_snapshot_at` string, date-time, nullable, required
      - `state` 'no_data' | 'ok' | 'partial', required
      - `target` string, required

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `402`: Deployment credits exhausted for a paid provider request
- `403`: Forbidden, or `byok_required`: the account runs paid provider work only on its own provider keys and none serves this request
- `404`: Not found
- `409`: Unsupported API version
- `422`: unsupported_target, unsupported_location, needs_reauth, lookup_failed, or cost_limit_exceeded
- `429`: budget_exhausted, in_progress, or rate_limited

---

[API](https://skmtc.dev/bisibility/apis/bisibility-public-api.md) · [All operations](https://skmtc.dev/bisibility/apis/bisibility-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bisibility/apis/bisibility-public-api/revisions/a6e1ec0dec82?raw)