---
title: "Analyze AI visibility"
method: POST
path: "/projects/{project_id}/ai-visibility"
tags: ["research-reports"]
---

# Analyze AI visibility

`POST /projects/{project_id}/ai-visibility`

## Request

- Base URL: `https://eu.bisibility.com/api/v1`
- URL: `https://eu.bisibility.com/api/v1/projects/{project_id}/ai-visibility`
- 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`)

Requires an explicit cost cap. estimate_only makes no paid request. Observed AI datasets and synthetic prompt tests remain distinct.

## Path parameters

- `project_id` string, required: The public project ID. Project membership and token scopes are enforced.

## Headers

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

## Request body

- object
  - `brand` string, required: Brand name to inspect.
  - `domain` string, required: Local citation-matching hostname, without a scheme or path. Domain searches remove a leading www. only from the provider filter and require at most 63 characters after removal; local matching keeps the full hostname. Brand searches and prompt comparisons allow up to 253.
  - `max_cost_cents` integer, required: Maximum accepted provider cost in cents. Estimates and cache reads do not spend credits.
  - `estimate_only` boolean: Return the cost estimate without paid provider I/O.
  - `fresh` boolean: Bypass the stored result and issue a new paid request when admitted.
  - `target_type` 'brand' | 'domain': Match a brand name or a domain.
  - `platform` 'chat_gpt' | 'google': Provider observed dataset: ChatGPT or Google AI Overview.
  - `location_code` integer: Provider location code.
  - `language_code` string: Dataset language.
  - `limit` integer: Maximum mention rows.

## Response `200`

Project-scoped result

- object
  - `data` union, required
    - object
      - `ok` unknown, required
      - `estimate` unknown, required
      - `estimated_cost_cents` number, required
      - `estimate_kind` 'forecast' | 'admission_bound', required
      - `is_guaranteed_maximum` boolean, required
      - `credential_source` 'own' | 'hosted', required
      - `estimate_credentials_ref` string, required
      - `is_partial_estimate` boolean
      - `pricing_policy` 'legacy_dated' | 'current_catalog' | 'provider_actual_cost'
      - `pricing_checked_at` union
        - string, date
        - string, date-time
      - `forecast_exclusions` string[]
      - `forecast_scope` 'tokens_and_base_only'
      - `forecast_assumptions` string[]
      - `evidence` 'observed_dataset' | 'synthetic_prompt_test', required
    - object
      - `ok` unknown, required
      - `estimate` unknown, required
      - `cached` boolean, required
      - `report_id` string, required
      - `cost_cents` number, required
      - `result` object, required
        - `evidence` 'observed_dataset' | 'synthetic_prompt_test', required
        - `rows` object[], required
          - `prompt` string, required
          - `model` string, required
          - `requested_model` string
          - `actual_model` string, nullable
          - `answer` string, required
          - `observed_at` string, nullable, required
          - `brand_mentioned` boolean, required
          - `domain_cited` boolean, required
          - `citations` object[], required
            - `title` string, required
            - `url` string, uri, required
            - `target_domain` boolean, required
          - `content_truncated` boolean
        - `total_available` integer, nullable, required
        - `truncated` boolean, required
        - `fetched_at` string, date-time, required
        - `cost_cents` number, required
        - `cost_status` 'confirmed' | 'unknown', required
        - `failure` string, nullable, required
      - `retry_blocked` boolean

## Other responses

- `400`: Invalid input
- `401`: Unauthorized
- `402`: Deployment credits exhausted for a paid provider request
- `403`: Project role or token scope denied, or `byok_required`: the account runs paid provider work only on its own provider keys and none serves this request
- `404`: Project or report not found
- `409`: Unsupported API version
- `422`: Provider unavailable or analysis cost cap exceeded
- `423`: Project is read-only
- `429`: Rate limited

## Changes

- **2026-10-19** `a6e1ec0dec82`: 1 info
  - the endpoint scheme security `AppOAuth` was added to the API

[Operation history](https://skmtc.dev/bisibility/apis/bisibility-public-api/changes/projects/:project_id/ai-visibility/post.md)

---

[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)