# AI visibility API reference

> Markdown version of https://autoranko.com/developers/api/ai-visibility. Base URL: https://autoranko.com/api/public/v1. OpenAPI 3.1: https://autoranko.com/api/public/v1/openapi.json.

Whether AI models name your business when buyers ask about your market. A run sends each brand-free prompt to each tracked model, once per sample (the plan sets how many), as the only message (no system prompt, no instruction to list companies), then reads which brands each answer names in a separate call. Every number carries its `mode`: `knowledge` is what the models answer from training data through the API, without web search, so ChatGPT.com or Claude.ai with browsing may answer differently; `search` appears only when a provider returned real search traces. Allowances are pooled per account (Free: 5 active prompts, 1 model family, 1 sample per prompt and model, monthly runs, 1 manual run a month; Starter: 20 active prompts, 2 model families, 2 samples per prompt and model, monthly runs, 2 manual runs a month; Pro: 50 active prompts, 2 model families, 2 samples per prompt and model, weekly runs, 4 manual runs a month; the model families available today are GPT and Claude).

## List tracked prompts

`GET https://autoranko.com/api/public/v1/sites/{id}/geo/prompts`

Scope: `geo:read`.

Returns the site's tracked prompts: the brand-free buyer questions a run asks each model. Active prompts come first, then the inactive ones that wait for room in the allowance, oldest first within each.

`allowance` shows the account's AI-visibility allowance, pooled across all of its sites: active prompts, manual runs this month, model families, samples and cadence. Suggest, write or import prompts in Dashboard → AI Visibility; add them from code with `POST /sites/{id}/geo/prompts`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Site ID, from `GET /sites`. |
| `intent` | query | string | no | Only prompts with this intent. An unknown value is rejected with `400 invalid_body`. One of: understanding, benefits, comparison, quality, selection. |
| `active` | query | boolean | no | `true`: only the active prompts that runs include. |

### Response 200

The site's prompts and the account allowance.

- `prompts` (object[]): Prompts, active first.
  - `id` (string): Prompt ID: a 64-bit integer serialized as a string.
  - `site_id` (string): ID of the site the prompt is tracked for.
  - `text` (string): The buyer question, exactly as sent to the models (3 to 300 characters). It never names the brand.
  - `intent` (string, one of understanding | benefits | comparison | quality | selection): What the buyer wants: `understanding`, `benefits`, `comparison`, `quality` or `selection`.
  - `source` (string, one of generated | manual | import | api): Where it came from: written by the AI-visibility prompt model (`generated`), typed in the dashboard (`manual`), imported (`import`) or added with this API (`api`).
  - `language` (string): Language code of the market it was written for, or an empty string.
  - `active` (boolean): `true` when runs include it. Active prompts count against the account's allowance; inactive ones wait.
  - `created_at` (string): When the prompt was added.
- `allowance` (object): The account's AI-visibility allowance.
  - `plan` (string, one of free | starter | pro): The account's plan.
  - `scope` (string, one of account): Always `account`: these allowances are shared by all of the account's sites.
  - `active_prompts_used` (integer): Active prompts across all of the account's sites.
  - `active_prompts_limit` (integer): Active prompts the plan allows (free 5, starter 20, pro 50).
  - `manual_runs_used` (integer): Manual runs started this calendar month (UTC) across the account's sites, from the dashboard and this API.
  - `manual_runs_limit` (integer): Manual runs the plan allows per calendar month. Scheduled runs don't count.
  - `models_limit` (integer): Model families (GPT, Claude) a run can track.
  - `samples_limit` (integer): Samples per prompt and model: repeats that measure how stable the answers are.
  - `cadence` (string, one of monthly | weekly): How often scheduled runs happen on this plan.

### Errors

- 400 `invalid_body`: `intent` isn't one of the five intents (`intent must be one of: understanding, benefits, comparison, quality, selection.`).
- 401 `missing_token`: The `Authorization: Bearer …` header is missing.
- 401 `invalid_token`: The token is malformed, unknown or revoked, or an OAuth token issued for another resource.
- 401 `token_expired`: The API key passed its expiry date, or the OAuth access token is more than an hour old.
- 403 `insufficient_scope`: The API key or OAuth connection doesn't have the `geo:read` scope.
- 404 `not_found`: No site with this `id` belongs to your account (`Site not found.`).
- 429 `rate_limited`: The key or OAuth connection made more than 120 requests in the last 60 seconds.

### Example request

```bash
curl https://autoranko.com/api/public/v1/sites/1/geo/prompts \
  -H "Authorization: Bearer $AUTORANKO_TOKEN"
```

### Example response (200) — illustrative

```json
{
  "prompts": [
    {
      "id": "41",
      "site_id": "1",
      "text": "Which irrigation company should I hire in Austin for a new drip system?",
      "intent": "selection",
      "source": "generated",
      "language": "en",
      "active": true,
      "created_at": "2026-11-05T14:02:11.418Z"
    },
    {
      "id": "42",
      "site_id": "1",
      "text": "Drip irrigation or sprinklers: which is better for a Texas lawn?",
      "intent": "comparison",
      "source": "generated",
      "language": "en",
      "active": true,
      "created_at": "2026-11-05T14:02:11.418Z"
    },
    {
      "id": "51",
      "site_id": "1",
      "text": "What should I check before hiring someone to repair my sprinklers?",
      "intent": "quality",
      "source": "manual",
      "language": "en",
      "active": true,
      "created_at": "2026-11-06T09:30:48.902Z"
    }
  ],
  "allowance": {
    "plan": "starter",
    "scope": "account",
    "active_prompts_used": 10,
    "active_prompts_limit": 20,
    "manual_runs_used": 1,
    "manual_runs_limit": 2,
    "models_limit": 2,
    "samples_limit": 2,
    "cadence": "monthly"
  }
}
```

## Add prompts

`POST https://autoranko.com/api/public/v1/sites/{id}/geo/prompts`

Scope: `geo:write`. Accepts an `Idempotency-Key` header (retries return the stored response).

Adds buyer questions to track for the site, active while the account's allowance lasts. Each prompt is trimmed and must be 3 to 300 characters long. A prompt that names your brand, an alias or one of your domains is rejected: a question like "is Acme any good?" measures nothing, so tracked prompts stay brand-free. A prompt the site already tracks is rejected too.

The response lists what was added and what wasn't, with the reason. Without `intent`, each prompt gets one from its wording (comparison, quality, selection, benefits or understanding words; selection otherwise).

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Site ID, from `GET /sites`. |
| `prompts` | body | string[] | yes | The questions, as a buyer would type them into an AI assistant: 1 to 50 strings. |
| `intent` | body | string | no | One intent for every prompt in the request. Omit it to label each prompt from its wording. One of: understanding, benefits, comparison, quality, selection. |

### Response 201

At least one prompt was added.

- `added` (object[]): The prompts added (active while the allowance lasted).
  - `id` (string): Prompt ID: a 64-bit integer serialized as a string.
  - `site_id` (string): ID of the site the prompt is tracked for.
  - `text` (string): The buyer question, exactly as sent to the models (3 to 300 characters). It never names the brand.
  - `intent` (string, one of understanding | benefits | comparison | quality | selection): What the buyer wants: `understanding`, `benefits`, `comparison`, `quality` or `selection`.
  - `source` (string, one of generated | manual | import | api): Where it came from: written by the AI-visibility prompt model (`generated`), typed in the dashboard (`manual`), imported (`import`) or added with this API (`api`).
  - `language` (string): Language code of the market it was written for, or an empty string.
  - `active` (boolean): `true` when runs include it. Active prompts count against the account's allowance; inactive ones wait.
  - `created_at` (string): When the prompt was added.
- `rejected` (object[]): Prompts that weren't added, with why.
  - `text` (string): The prompt as sent.
  - `reason` (string): Why it wasn't added.
- `allowance` (object): The allowance after the change.
  - `plan` (string, one of free | starter | pro): The account's plan.
  - `scope` (string, one of account): Always `account`: these allowances are shared by all of the account's sites.
  - `active_prompts_used` (integer): Active prompts across all of the account's sites.
  - `active_prompts_limit` (integer): Active prompts the plan allows (free 5, starter 20, pro 50).
  - `manual_runs_used` (integer): Manual runs started this calendar month (UTC) across the account's sites, from the dashboard and this API.
  - `manual_runs_limit` (integer): Manual runs the plan allows per calendar month. Scheduled runs don't count.
  - `models_limit` (integer): Model families (GPT, Claude) a run can track.
  - `samples_limit` (integer): Samples per prompt and model: repeats that measure how stable the answers are.
  - `cadence` (string, one of monthly | weekly): How often scheduled runs happen on this plan.

### Errors

- 400 `invalid_body`: The body isn't valid JSON (`Invalid JSON body.`).
- 400 `invalid_body`: `prompts` is missing, empty, longer than 50 items or not all strings (`prompts must be a non-empty array of strings (at most 50).`).
- 400 `invalid_body`: `intent` isn't one of the five intents (`intent must be one of: understanding, benefits, comparison, quality, selection.`).
- 400 `invalid_body`: No prompt could be added (`None of the prompts could be added. …`, followed by the first reason).
- 401 `missing_token`: The `Authorization: Bearer …` header is missing.
- 401 `invalid_token`: The token is malformed, unknown or revoked, or an OAuth token issued for another resource.
- 401 `token_expired`: The API key passed its expiry date, or the OAuth access token is more than an hour old.
- 403 `insufficient_scope`: The API key or OAuth connection doesn't have the `geo:write` scope.
- 404 `not_found`: No site with this `id` belongs to your account (`Site not found.`).
- 409 `idempotency_conflict`: The `Idempotency-Key` was already used for a different request in the last 24 hours.
- 409 `idempotency_in_progress`: A request with the same `Idempotency-Key` is still running.
- 429 `rate_limited`: The key or OAuth connection made more than 120 requests in the last 60 seconds.
- 429 `plan_limit`: The account already has as many active prompts as its plan allows (`Your plan's AI-visibility prompt allowance is full (20 active prompts across your sites on the starter plan). Archive prompts or upgrade.`).

### Example request

```bash
curl -X POST https://autoranko.com/api/public/v1/sites/1/geo/prompts \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": [
      "How much does a smart irrigation controller save on water bills?",
      "Is Greenfield Irrigation any good?"
    ]
  }'
```

### Example response (201) — illustrative

```json
{
  "added": [
    {
      "id": "52",
      "site_id": "1",
      "text": "How much does a smart irrigation controller save on water bills?",
      "intent": "benefits",
      "source": "api",
      "language": "en",
      "active": true,
      "created_at": "2026-11-07T10:15:02.337Z"
    }
  ],
  "rejected": [
    {
      "text": "Is Greenfield Irrigation any good?",
      "reason": "Names your brand or domain. Tracked prompts stay brand-free so the answer isn't steered."
    }
  ],
  "allowance": {
    "plan": "starter",
    "scope": "account",
    "active_prompts_used": 11,
    "active_prompts_limit": 20,
    "manual_runs_used": 1,
    "manual_runs_limit": 2,
    "models_limit": 2,
    "samples_limit": 2,
    "cadence": "monthly"
  }
}
```

## Start a run

`POST https://autoranko.com/api/public/v1/sites/{id}/geo/runs`

Scope: `geo:write`. Accepts an `Idempotency-Key` header (retries return the stored response).

Starts an AI-visibility run now: every active prompt of the site, asked of every tracked model, `samples` times each. The call returns `201` right away with the run `queued`; answers are collected in the background (a first batch at once, the rest by the hourly scheduler), so a run takes from a few minutes to a few hours. Follow it with `GET /geo/runs/{id}` or the `geo.run.completed` webhook.

Manual runs count against the plan's manual runs per month, pooled per account; scheduled runs (free monthly, starter monthly, pro weekly) don't. The run uses `mode: search` only when every tracked model has a live-search provider on this server; otherwise it measures model knowledge and says why in `notes`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Site ID, from `GET /sites`. |

### Response 201

The run was created in `queued`.

- `run` (object): The new run.
  - `id` (string): Run ID: a 64-bit integer serialized as a string.
  - `site_id` (string): ID of the site.
  - `trigger` (string, one of cron | manual | api): What started it: the schedule (`cron`), the dashboard (`manual`) or this API (`api`).
  - `mode` (string, one of knowledge | search): How the answers behind this number were produced: `knowledge` (the bare question through the API, no web search) or `search` (the model ran web searches and the provider returned the traces). The two are never mixed.
  - `status` (string, one of queued | running | done | partial | failed): `queued` and `running` while answers come in; then `done` (every answer received), `partial` (some failed: see `model_stats`) or `failed` (none received).
  - `models` (string[]): The tracked models, one per family.
  - `samples` (integer): Times each prompt was asked of each model.
  - `prompt_count` (integer): Prompts in the run.
  - `expected` (integer): Answers the run asks for: `prompt_count` × models × `samples`.
  - `completed` (integer): Answers received so far.
  - `failed` (integer): Answers that failed so far.
  - `visibility` (number, nullable): Share of received answers that name the brand. `null` until the run has finished. A number from 0 to 1, or `null` with nothing to count.
  - `model_stats` (object[]): Per-model results, once the run has finished (empty before).
    - `model` (string): The tracked model, such as `gpt-6-astra` or `claude-sonnet-5-5`. Answers are attributed to the model asked, never to a fallback.
    - `provider` (string, nullable, one of kie | openai | anthropic | dataforseo): Which service answered for it, or `null` if none did.
    - `mode` (string, one of knowledge | search): How the answers behind this number were produced: `knowledge` (the bare question through the API, no web search) or `search` (the model ran web searches and the provider returned the traces). The two are never mixed.
    - `completed` (integer): Answers received.
    - `failed` (integer): Answers that failed (the model or its relay was unavailable, timed out, or returned nothing).
    - `mentioned` (integer): Received answers that name the brand, an alias or one of its domains.
    - `visibility` (number, nullable): `mentioned` / `completed`. A number from 0 to 1, or `null` with nothing to count.
    - `avg_mention_rank` (number, nullable): Average position of the brand among the names an answer lists (1 = named first), over the answers that name it; `null` when none does.
    - `last_error` (string, nullable): The last failure for this model in the run, or `null`.
  - `notes` (string, nullable): Why the run differs from the settings (for example, live search requested but unavailable), or `null`.
  - `error` (string, nullable): Why a `failed` run failed, or `null`.
  - `created_at` (string): When the run was started.
  - `started_at` (string, nullable): When the first answer was requested, or `null`.
  - `finished_at` (string, nullable): When the run finished, or `null` while it's open.

### Errors

- 401 `missing_token`: The `Authorization: Bearer …` header is missing.
- 401 `invalid_token`: The token is malformed, unknown or revoked, or an OAuth token issued for another resource.
- 401 `token_expired`: The API key passed its expiry date, or the OAuth access token is more than an hour old.
- 403 `insufficient_scope`: The API key or OAuth connection doesn't have the `geo:write` scope.
- 404 `not_found`: No site with this `id` belongs to your account (`Site not found.`).
- 409 `invalid_state`: A run is already queued or running for the site (`An AI-visibility run is already in progress for this site.`).
- 409 `invalid_state`: The site has no active prompt (`Add prompts before starting a run.`).
- 409 `idempotency_conflict`: The `Idempotency-Key` was already used for a different request in the last 24 hours.
- 409 `idempotency_in_progress`: A request with the same `Idempotency-Key` is still running.
- 429 `rate_limited`: The key or OAuth connection made more than 120 requests in the last 60 seconds.
- 429 `plan_limit`: The account has used its manual runs for the month (`Manual AI-visibility runs used up for this month (1 on the free plan). Scheduled runs continue.`).

### Example request

```bash
curl -X POST https://autoranko.com/api/public/v1/sites/1/geo/runs \
  -H "Authorization: Bearer $AUTORANKO_TOKEN"
```

### Example response (201) — illustrative

```json
{
  "run": {
    "id": "13",
    "site_id": "1",
    "trigger": "manual",
    "mode": "knowledge",
    "status": "queued",
    "models": [
      "gpt-6-astra",
      "claude-sonnet-5-5"
    ],
    "samples": 2,
    "prompt_count": 10,
    "expected": 40,
    "completed": 0,
    "failed": 0,
    "visibility": null,
    "model_stats": [],
    "notes": null,
    "error": null,
    "created_at": "2026-11-07T10:20:41.006Z",
    "started_at": null,
    "finished_at": null
  }
}
```

> There's no idempotency key: a retried request after a timeout gets `409 invalid_state` if the first one created the run.

## List runs

`GET https://autoranko.com/api/public/v1/sites/{id}/geo/runs`

Scope: `geo:read`.

Lists the site's AI-visibility runs, newest first, scheduled and manual. An open run (`queued` or `running`) shows its answers received and failed so far; `visibility` and `model_stats` appear once it has finished.

Compare runs only within one `mode`: knowledge and search measure different things.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Site ID, from `GET /sites`. |
| `limit` | query | integer | no | How many of the newest runs to return. Values outside 1–100 are clamped. Default: 20. |

### Response 200

The newest runs.

- `runs` (object[]): Runs, newest first.
  - `id` (string): Run ID: a 64-bit integer serialized as a string.
  - `site_id` (string): ID of the site.
  - `trigger` (string, one of cron | manual | api): What started it: the schedule (`cron`), the dashboard (`manual`) or this API (`api`).
  - `mode` (string, one of knowledge | search): How the answers behind this number were produced: `knowledge` (the bare question through the API, no web search) or `search` (the model ran web searches and the provider returned the traces). The two are never mixed.
  - `status` (string, one of queued | running | done | partial | failed): `queued` and `running` while answers come in; then `done` (every answer received), `partial` (some failed: see `model_stats`) or `failed` (none received).
  - `models` (string[]): The tracked models, one per family.
  - `samples` (integer): Times each prompt was asked of each model.
  - `prompt_count` (integer): Prompts in the run.
  - `expected` (integer): Answers the run asks for: `prompt_count` × models × `samples`.
  - `completed` (integer): Answers received so far.
  - `failed` (integer): Answers that failed so far.
  - `visibility` (number, nullable): Share of received answers that name the brand. `null` until the run has finished. A number from 0 to 1, or `null` with nothing to count.
  - `model_stats` (object[]): Per-model results, once the run has finished (empty before).
    - `model` (string): The tracked model, such as `gpt-6-astra` or `claude-sonnet-5-5`. Answers are attributed to the model asked, never to a fallback.
    - `provider` (string, nullable, one of kie | openai | anthropic | dataforseo): Which service answered for it, or `null` if none did.
    - `mode` (string, one of knowledge | search): How the answers behind this number were produced: `knowledge` (the bare question through the API, no web search) or `search` (the model ran web searches and the provider returned the traces). The two are never mixed.
    - `completed` (integer): Answers received.
    - `failed` (integer): Answers that failed (the model or its relay was unavailable, timed out, or returned nothing).
    - `mentioned` (integer): Received answers that name the brand, an alias or one of its domains.
    - `visibility` (number, nullable): `mentioned` / `completed`. A number from 0 to 1, or `null` with nothing to count.
    - `avg_mention_rank` (number, nullable): Average position of the brand among the names an answer lists (1 = named first), over the answers that name it; `null` when none does.
    - `last_error` (string, nullable): The last failure for this model in the run, or `null`.
  - `notes` (string, nullable): Why the run differs from the settings (for example, live search requested but unavailable), or `null`.
  - `error` (string, nullable): Why a `failed` run failed, or `null`.
  - `created_at` (string): When the run was started.
  - `started_at` (string, nullable): When the first answer was requested, or `null`.
  - `finished_at` (string, nullable): When the run finished, or `null` while it's open.

### Errors

- 401 `missing_token`: The `Authorization: Bearer …` header is missing.
- 401 `invalid_token`: The token is malformed, unknown or revoked, or an OAuth token issued for another resource.
- 401 `token_expired`: The API key passed its expiry date, or the OAuth access token is more than an hour old.
- 403 `insufficient_scope`: The API key or OAuth connection doesn't have the `geo:read` scope.
- 404 `not_found`: No site with this `id` belongs to your account (`Site not found.`).
- 429 `rate_limited`: The key or OAuth connection made more than 120 requests in the last 60 seconds.

### Example request

```bash
curl "https://autoranko.com/api/public/v1/sites/1/geo/runs?limit=10" \
  -H "Authorization: Bearer $AUTORANKO_TOKEN"
```

### Example response (200) — illustrative

```json
{
  "runs": [
    {
      "id": "12",
      "site_id": "1",
      "trigger": "manual",
      "mode": "knowledge",
      "status": "partial",
      "models": [
        "gpt-6-astra",
        "claude-sonnet-5-5"
      ],
      "samples": 2,
      "prompt_count": 10,
      "expected": 40,
      "completed": 30,
      "failed": 10,
      "visibility": 0.2333,
      "model_stats": [
        {
          "model": "gpt-6-astra",
          "provider": "kie",
          "mode": "knowledge",
          "completed": 20,
          "failed": 0,
          "mentioned": 6,
          "visibility": 0.3,
          "avg_mention_rank": 2.5,
          "last_error": null
        },
        {
          "model": "claude-sonnet-5-5",
          "provider": "kie",
          "mode": "knowledge",
          "completed": 10,
          "failed": 10,
          "mentioned": 1,
          "visibility": 0.1,
          "avg_mention_rank": 3,
          "last_error": "Resources are tight, please try again later."
        }
      ],
      "notes": null,
      "error": null,
      "created_at": "2026-11-07T08:00:04.112Z",
      "started_at": "2026-11-07T08:00:05.020Z",
      "finished_at": "2026-11-07T09:01:37.874Z"
    }
  ]
}
```

## Get a run with its answers

`GET https://autoranko.com/api/public/v1/geo/runs/{id}`

Scope: `geo:read`.

Returns one run and a page of its answers: the full text of each, which names it gives (`entities`, in order) and whether it names your brand. Answers are ordered by prompt, model and sample.

A failed answer stays failed for the model it was asked of: it's never retried on another model, because the answer would then be attributed to the wrong one. In `knowledge` mode, `urls_written` holds URLs the model wrote from memory (unverified, never sources) and `citations` is empty.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Run ID, from `POST /sites/{id}/geo/runs` or `GET /sites/{id}/geo/runs`. |
| `limit` | query | integer | no | Answers per page. Values outside 1–500 are clamped. Default: 100. |
| `offset` | query | integer | no | Answers to skip, for pagination. Default: 0. |
| `model` | query | string | no | Only this model's answers, such as `gpt-6-astra`. |
| `status` | query | string | no | Only answers in this status. An unknown value is rejected with `400 invalid_body`. One of: pending, running, ok, failed. |

### Response 200

The run and one page of its answers.

- `run` (object): The run.
  - `id` (string): Run ID: a 64-bit integer serialized as a string.
  - `site_id` (string): ID of the site.
  - `trigger` (string, one of cron | manual | api): What started it: the schedule (`cron`), the dashboard (`manual`) or this API (`api`).
  - `mode` (string, one of knowledge | search): How the answers behind this number were produced: `knowledge` (the bare question through the API, no web search) or `search` (the model ran web searches and the provider returned the traces). The two are never mixed.
  - `status` (string, one of queued | running | done | partial | failed): `queued` and `running` while answers come in; then `done` (every answer received), `partial` (some failed: see `model_stats`) or `failed` (none received).
  - `models` (string[]): The tracked models, one per family.
  - `samples` (integer): Times each prompt was asked of each model.
  - `prompt_count` (integer): Prompts in the run.
  - `expected` (integer): Answers the run asks for: `prompt_count` × models × `samples`.
  - `completed` (integer): Answers received so far.
  - `failed` (integer): Answers that failed so far.
  - `visibility` (number, nullable): Share of received answers that name the brand. `null` until the run has finished. A number from 0 to 1, or `null` with nothing to count.
  - `model_stats` (object[]): Per-model results, once the run has finished (empty before).
    - `model` (string): The tracked model, such as `gpt-6-astra` or `claude-sonnet-5-5`. Answers are attributed to the model asked, never to a fallback.
    - `provider` (string, nullable, one of kie | openai | anthropic | dataforseo): Which service answered for it, or `null` if none did.
    - `mode` (string, one of knowledge | search): How the answers behind this number were produced: `knowledge` (the bare question through the API, no web search) or `search` (the model ran web searches and the provider returned the traces). The two are never mixed.
    - `completed` (integer): Answers received.
    - `failed` (integer): Answers that failed (the model or its relay was unavailable, timed out, or returned nothing).
    - `mentioned` (integer): Received answers that name the brand, an alias or one of its domains.
    - `visibility` (number, nullable): `mentioned` / `completed`. A number from 0 to 1, or `null` with nothing to count.
    - `avg_mention_rank` (number, nullable): Average position of the brand among the names an answer lists (1 = named first), over the answers that name it; `null` when none does.
    - `last_error` (string, nullable): The last failure for this model in the run, or `null`.
  - `notes` (string, nullable): Why the run differs from the settings (for example, live search requested but unavailable), or `null`.
  - `error` (string, nullable): Why a `failed` run failed, or `null`.
  - `created_at` (string): When the run was started.
  - `started_at` (string, nullable): When the first answer was requested, or `null`.
  - `finished_at` (string, nullable): When the run finished, or `null` while it's open.
- `answers` (object[]): One page of answers.
  - `id` (string): Answer ID: a 64-bit integer serialized as a string.
  - `run_id` (string): ID of the run.
  - `prompt_id` (string, nullable): ID of the prompt, or `null` if the prompt was deleted.
  - `prompt_text` (string): The exact text that was sent, as it was when the run started.
  - `intent` (string, one of understanding | benefits | comparison | quality | selection): The prompt's intent at the time.
  - `model` (string): The model asked. The answer is attributed to it and nothing else.
  - `model_served` (string, nullable): The model the provider reported it ran, or `null` before an answer.
  - `provider` (string, one of kie | openai | anthropic | dataforseo): The service that answered.
  - `mode` (string, one of knowledge | search): How the answers behind this number were produced: `knowledge` (the bare question through the API, no web search) or `search` (the model ran web searches and the provider returned the traces). The two are never mixed.
  - `sample` (integer): Which repeat of this prompt and model (1 to the run's `samples`).
  - `status` (string, one of pending | running | ok | failed): `pending` and `running` until answered, then `ok` or `failed`.
  - `answer` (string, nullable): The full answer text, or `null` until there is one.
  - `error` (string, nullable): Why the answer failed, or `null`.
  - `mentioned` (boolean, nullable): Whether the answer names the brand, an alias or one of its domains (exact match). `null` unless `status` is `ok`.
  - `mention_rank` (integer, nullable): Position of the brand among the names the answer lists, or `null` when it isn't named or the order couldn't be read.
  - `domain_mentioned` (boolean, nullable): Whether one of the site's domains appears in the answer. `null` unless `status` is `ok`.
  - `entities` (object[]): Every company, brand or product the answer names, in order (read by a separate extraction call).
    - `name` (string): A company, brand or product the answer names, as written (your brand under its brand name).
    - `domain` (string, nullable): Its domain when the answer writes one, else `null`.
    - `rank` (integer): Order of first appearance in the answer (1 = first).
    - `brand` (boolean): `true` for your brand (matched exactly on its name, aliases or domains).
  - `urls_written` (object[]): URLs written in the answer text. In `knowledge` mode these are URLs the model wrote from memory: unverified, never sources.
    - `url` (string): The URL.
    - `domain` (string): Its registrable domain, such as `example.co.uk`.
    - `title` (string, optional): The page title the provider returned (citations only).
  - `searches` (string[]): Search queries: observed in the provider's traces (`searches_kind: observed`) or what the model said it would search when asked separately (`predicted`).
  - `searches_kind` (string, one of observed | predicted | none): `observed` (tool traces), `predicted` (asked separately; not observed) or `none`.
  - `citations` (object[]): Sources the provider returned with a `search` answer. Always empty in `knowledge` mode.
    - `url` (string): The URL.
    - `domain` (string): Its registrable domain, such as `example.co.uk`.
    - `title` (string, optional): The page title the provider returned (citations only).
  - `created_at` (string): When the answer was queued.
  - `answered_at` (string, nullable): When it was answered or failed, or `null`.
- `limit` (integer): The page size applied.
- `offset` (integer): The offset applied.

### Errors

- 400 `invalid_body`: `status` isn't an answer status (`status must be one of: pending, running, ok, failed.`).
- 401 `missing_token`: The `Authorization: Bearer …` header is missing.
- 401 `invalid_token`: The token is malformed, unknown or revoked, or an OAuth token issued for another resource.
- 401 `token_expired`: The API key passed its expiry date, or the OAuth access token is more than an hour old.
- 403 `insufficient_scope`: The API key or OAuth connection doesn't have the `geo:read` scope.
- 404 `not_found`: No run with this `id` belongs to your account (`Run not found.`).
- 429 `rate_limited`: The key or OAuth connection made more than 120 requests in the last 60 seconds.

### Example request

```bash
curl "https://autoranko.com/api/public/v1/geo/runs/12?status=ok&limit=100" \
  -H "Authorization: Bearer $AUTORANKO_TOKEN"
```

### Example response (200) — illustrative

```json
{
  "run": {
    "id": "12",
    "site_id": "1",
    "trigger": "manual",
    "mode": "knowledge",
    "status": "partial",
    "models": [
      "gpt-6-astra",
      "claude-sonnet-5-5"
    ],
    "samples": 2,
    "prompt_count": 10,
    "expected": 40,
    "completed": 30,
    "failed": 10,
    "visibility": 0.2333,
    "model_stats": [
      {
        "model": "gpt-6-astra",
        "provider": "kie",
        "mode": "knowledge",
        "completed": 20,
        "failed": 0,
        "mentioned": 6,
        "visibility": 0.3,
        "avg_mention_rank": 2.5,
        "last_error": null
      },
      {
        "model": "claude-sonnet-5-5",
        "provider": "kie",
        "mode": "knowledge",
        "completed": 10,
        "failed": 10,
        "mentioned": 1,
        "visibility": 0.1,
        "avg_mention_rank": 3,
        "last_error": "Resources are tight, please try again later."
      }
    ],
    "notes": null,
    "error": null,
    "created_at": "2026-11-07T08:00:04.112Z",
    "started_at": "2026-11-07T08:00:05.020Z",
    "finished_at": "2026-11-07T09:01:37.874Z"
  },
  "answers": [
    {
      "id": "905",
      "run_id": "12",
      "prompt_id": "41",
      "prompt_text": "Which irrigation company should I hire in Austin for a new drip system?",
      "intent": "selection",
      "model": "gpt-6-astra",
      "model_served": "gpt-6-astra",
      "provider": "kie",
      "mode": "knowledge",
      "sample": 1,
      "status": "ok",
      "answer": "For a new drip system in Austin, homeowners often compare a few local installers:\n\n1. **Lone Star Lawn & Irrigation**: full-service design and install, licensed irrigators.\n2. **Greenfield Irrigation** (https://demo.autoranko.com): focuses on drip conversions and smart controllers.\n3. **Hill Country Irrigation**: smaller crew, good for repairs and add-ons.\n\nAsk each for a licensed irrigator (Texas requires one), a written water-budget estimate and a warranty on parts and labor.",
      "error": null,
      "mentioned": true,
      "mention_rank": 2,
      "domain_mentioned": true,
      "entities": [
        {
          "name": "Lone Star Lawn & Irrigation",
          "domain": null,
          "rank": 1,
          "brand": false
        },
        {
          "name": "Greenfield Irrigation",
          "domain": "demo.autoranko.com",
          "rank": 2,
          "brand": true
        },
        {
          "name": "Hill Country Irrigation",
          "domain": null,
          "rank": 3,
          "brand": false
        }
      ],
      "urls_written": [
        {
          "url": "https://demo.autoranko.com",
          "domain": "demo.autoranko.com"
        }
      ],
      "searches": [],
      "searches_kind": "none",
      "citations": [],
      "created_at": "2026-11-07T08:00:04.112Z",
      "answered_at": "2026-11-07T08:00:31.560Z"
    },
    {
      "id": "906",
      "run_id": "12",
      "prompt_id": "41",
      "prompt_text": "Which irrigation company should I hire in Austin for a new drip system?",
      "intent": "selection",
      "model": "claude-sonnet-5-5",
      "model_served": null,
      "provider": "kie",
      "mode": "knowledge",
      "sample": 1,
      "status": "failed",
      "answer": null,
      "error": "Resources are tight, please try again later.",
      "mentioned": null,
      "mention_rank": null,
      "domain_mentioned": null,
      "entities": [],
      "urls_written": [],
      "searches": [],
      "searches_kind": "none",
      "citations": [],
      "created_at": "2026-11-07T08:00:04.112Z",
      "answered_at": "2026-11-07T08:03:12.004Z"
    }
  ],
  "limit": 2,
  "offset": 0
}
```

## Get visibility metrics

`GET https://autoranko.com/api/public/v1/sites/{id}/geo/stats`

Scope: `geo:read`.

Returns the metrics of the site's latest finished run in one mode: visibility (share of answers that name your brand), average mention rank, share of voice, stability across samples, and the same per model, per intent and per prompt, plus the trend of that mode's runs. `by_prompt` lists the least visible prompts first: they are the questions to write content for.

Every number belongs to one `mode`, and `disclaimer` is the label to show with it. Model knowledge: what GPT-6 Astra / Claude Sonnet 5.5 answer from training data via API, without web search. ChatGPT.com or Claude.ai with browsing may answer differently. Knowledge and search runs never share a trend.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Site ID, from `GET /sites`. |
| `mode` | query | string | no | The mode to report. Without it: the mode of the latest finished run. An unknown value is rejected with `400 invalid_body`. One of: knowledge, search. |

### Response 200

The metrics.

- `stats` (object): AI-visibility metrics.
  - `site_id` (string): ID of the site.
  - `mode` (string, one of knowledge | search): How the answers behind this number were produced: `knowledge` (the bare question through the API, no web search) or `search` (the model ran web searches and the provider returned the traces). The two are never mixed.
  - `disclaimer` (string): The label that goes with every number of this mode, naming the tracked models. Show it next to them.
  - `modes_available` (string[], one of knowledge | search): Modes with at least one finished run.
  - `run` (object, nullable): The latest finished run of this mode, which the metrics below describe, or `null` before the first one.
    - `id` (string): Run ID: a 64-bit integer serialized as a string.
    - `site_id` (string): ID of the site.
    - `trigger` (string, one of cron | manual | api): What started it: the schedule (`cron`), the dashboard (`manual`) or this API (`api`).
    - `mode` (string, one of knowledge | search): How the answers behind this number were produced: `knowledge` (the bare question through the API, no web search) or `search` (the model ran web searches and the provider returned the traces). The two are never mixed.
    - `status` (string, one of queued | running | done | partial | failed): `queued` and `running` while answers come in; then `done` (every answer received), `partial` (some failed: see `model_stats`) or `failed` (none received).
    - `models` (string[]): The tracked models, one per family.
    - `samples` (integer): Times each prompt was asked of each model.
    - `prompt_count` (integer): Prompts in the run.
    - `expected` (integer): Answers the run asks for: `prompt_count` × models × `samples`.
    - `completed` (integer): Answers received so far.
    - `failed` (integer): Answers that failed so far.
    - `visibility` (number, nullable): Share of received answers that name the brand. `null` until the run has finished. A number from 0 to 1, or `null` with nothing to count.
    - `model_stats` (object[]): Per-model results, once the run has finished (empty before).
      - `model` (string): The tracked model, such as `gpt-6-astra` or `claude-sonnet-5-5`. Answers are attributed to the model asked, never to a fallback.
      - `provider` (string, nullable, one of kie | openai | anthropic | dataforseo): Which service answered for it, or `null` if none did.
      - `mode` (string, one of knowledge | search): How the answers behind this number were produced: `knowledge` (the bare question through the API, no web search) or `search` (the model ran web searches and the provider returned the traces). The two are never mixed.
      - `completed` (integer): Answers received.
      - `failed` (integer): Answers that failed (the model or its relay was unavailable, timed out, or returned nothing).
      - `mentioned` (integer): Received answers that name the brand, an alias or one of its domains.
      - `visibility` (number, nullable): `mentioned` / `completed`. A number from 0 to 1, or `null` with nothing to count.
      - `avg_mention_rank` (number, nullable): Average position of the brand among the names an answer lists (1 = named first), over the answers that name it; `null` when none does.
      - `last_error` (string, nullable): The last failure for this model in the run, or `null`.
    - `notes` (string, nullable): Why the run differs from the settings (for example, live search requested but unavailable), or `null`.
    - `error` (string, nullable): Why a `failed` run failed, or `null`.
    - `created_at` (string): When the run was started.
    - `started_at` (string, nullable): When the first answer was requested, or `null`.
    - `finished_at` (string, nullable): When the run finished, or `null` while it's open.
  - `visibility` (number, nullable): Share of the run's answers that name the brand. A number from 0 to 1, or `null` with nothing to count.
  - `avg_mention_rank` (number, nullable): Average position of the brand where it is named, or `null`.
  - `share_of_voice` (number, nullable): Brand mentions / all name mentions in the run's answers (each answer counts each name once). A number from 0 to 1, or `null` with nothing to count.
  - `stability` (number, nullable): Share of prompt × model pairs whose samples agree (all name the brand, or none). `null` with one sample. A number from 0 to 1, or `null` with nothing to count.
  - `samples` (integer): Samples per prompt and model in the run.
  - `by_model` (object[]): The same metrics per tracked model.
    - `model` (string): The model.
    - `mode` (string, one of knowledge | search): How the answers behind this number were produced: `knowledge` (the bare question through the API, no web search) or `search` (the model ran web searches and the provider returned the traces). The two are never mixed.
    - `completed` (integer): Answers received.
    - `mentioned` (integer): Answers that name the brand.
    - `visibility` (number, nullable): `mentioned` / `completed`. A number from 0 to 1, or `null` with nothing to count.
    - `avg_mention_rank` (number, nullable): Average position where named, or `null`.
    - `share_of_voice` (number, nullable): Share of voice in this model's answers. A number from 0 to 1, or `null` with nothing to count.
    - `stability` (number, nullable): Stability of this model's answers. A number from 0 to 1, or `null` with nothing to count.
  - `by_intent` (object[]): Visibility per prompt intent.
    - `intent` (string, one of understanding | benefits | comparison | quality | selection): The intent.
    - `mode` (string, one of knowledge | search): How the answers behind this number were produced: `knowledge` (the bare question through the API, no web search) or `search` (the model ran web searches and the provider returned the traces). The two are never mixed.
    - `completed` (integer): Answers received.
    - `mentioned` (integer): Answers that name the brand.
    - `visibility` (number, nullable): `mentioned` / `completed`. A number from 0 to 1, or `null` with nothing to count.
  - `by_prompt` (object[]): Visibility per prompt, least visible first: the prompts to write content for.
    - `prompt_id` (string, nullable): ID of the prompt, or `null`.
    - `text` (string): The prompt as sent.
    - `intent` (string, one of understanding | benefits | comparison | quality | selection): Its intent.
    - `mode` (string, one of knowledge | search): How the answers behind this number were produced: `knowledge` (the bare question through the API, no web search) or `search` (the model ran web searches and the provider returned the traces). The two are never mixed.
    - `completed` (integer): Answers received.
    - `mentioned` (integer): Answers that name the brand.
    - `visibility` (number, nullable): `mentioned` / `completed`. A number from 0 to 1, or `null` with nothing to count.
    - `by_model` (object[]): Per model.
      - `model` (string): The model.
      - `completed` (integer): Answers received.
      - `mentioned` (integer): Answers that name the brand.
      - `visibility` (number, nullable): `mentioned` / `completed`. A number from 0 to 1, or `null` with nothing to count.
  - `trend` (object[]): Finished runs of the same mode, oldest first (at most 26). Knowledge and search runs never share a trend.
    - `run_id` (string): ID of the run.
    - `finished_at` (string, nullable): When it finished.
    - `mode` (string, one of knowledge | search): How the answers behind this number were produced: `knowledge` (the bare question through the API, no web search) or `search` (the model ran web searches and the provider returned the traces). The two are never mixed.
    - `visibility` (number, nullable): The run's visibility. A number from 0 to 1, or `null` with nothing to count.
    - `by_model` (object[]): Per model.
      - `model` (string): The model.
      - `visibility` (number, nullable): The model's visibility in that run. A number from 0 to 1, or `null` with nothing to count.

### Errors

- 400 `invalid_body`: `mode` isn't `knowledge` or `search` (`mode must be one of: knowledge, search.`).
- 401 `missing_token`: The `Authorization: Bearer …` header is missing.
- 401 `invalid_token`: The token is malformed, unknown or revoked, or an OAuth token issued for another resource.
- 401 `token_expired`: The API key passed its expiry date, or the OAuth access token is more than an hour old.
- 403 `insufficient_scope`: The API key or OAuth connection doesn't have the `geo:read` scope.
- 404 `not_found`: No site with this `id` belongs to your account (`Site not found.`).
- 429 `rate_limited`: The key or OAuth connection made more than 120 requests in the last 60 seconds.

### Example request

```bash
curl "https://autoranko.com/api/public/v1/sites/1/geo/stats?mode=knowledge" \
  -H "Authorization: Bearer $AUTORANKO_TOKEN"
```

### Example response (200) — illustrative

```json
{
  "stats": {
    "site_id": "1",
    "mode": "knowledge",
    "disclaimer": "Model knowledge: what GPT-6 Astra / Claude Sonnet 5.5 answer from training data via API, without web search. ChatGPT.com or Claude.ai with browsing may answer differently.",
    "modes_available": [
      "knowledge"
    ],
    "run": {
      "id": "12",
      "site_id": "1",
      "trigger": "manual",
      "mode": "knowledge",
      "status": "partial",
      "models": [
        "gpt-6-astra",
        "claude-sonnet-5-5"
      ],
      "samples": 2,
      "prompt_count": 10,
      "expected": 40,
      "completed": 30,
      "failed": 10,
      "visibility": 0.2333,
      "model_stats": [
        {
          "model": "gpt-6-astra",
          "provider": "kie",
          "mode": "knowledge",
          "completed": 20,
          "failed": 0,
          "mentioned": 6,
          "visibility": 0.3,
          "avg_mention_rank": 2.5,
          "last_error": null
        },
        {
          "model": "claude-sonnet-5-5",
          "provider": "kie",
          "mode": "knowledge",
          "completed": 10,
          "failed": 10,
          "mentioned": 1,
          "visibility": 0.1,
          "avg_mention_rank": 3,
          "last_error": "Resources are tight, please try again later."
        }
      ],
      "notes": null,
      "error": null,
      "created_at": "2026-11-07T08:00:04.112Z",
      "started_at": "2026-11-07T08:00:05.020Z",
      "finished_at": "2026-11-07T09:01:37.874Z"
    },
    "visibility": 0.2333,
    "avg_mention_rank": 2.57,
    "share_of_voice": 0.1129,
    "stability": 0.8,
    "samples": 2,
    "by_model": [
      {
        "model": "gpt-6-astra",
        "mode": "knowledge",
        "completed": 20,
        "mentioned": 6,
        "visibility": 0.3,
        "avg_mention_rank": 2.5,
        "share_of_voice": 0.1364,
        "stability": 0.8
      },
      {
        "model": "claude-sonnet-5-5",
        "mode": "knowledge",
        "completed": 10,
        "mentioned": 1,
        "visibility": 0.1,
        "avg_mention_rank": 3,
        "share_of_voice": 0.0556,
        "stability": null
      }
    ],
    "by_intent": [
      {
        "intent": "comparison",
        "mode": "knowledge",
        "completed": 6,
        "mentioned": 0,
        "visibility": 0
      },
      {
        "intent": "selection",
        "mode": "knowledge",
        "completed": 9,
        "mentioned": 4,
        "visibility": 0.4444
      }
    ],
    "by_prompt": [
      {
        "prompt_id": "42",
        "text": "Drip irrigation or sprinklers: which is better for a Texas lawn?",
        "intent": "comparison",
        "mode": "knowledge",
        "completed": 3,
        "mentioned": 0,
        "visibility": 0,
        "by_model": [
          {
            "model": "gpt-6-astra",
            "completed": 2,
            "mentioned": 0,
            "visibility": 0
          },
          {
            "model": "claude-sonnet-5-5",
            "completed": 1,
            "mentioned": 0,
            "visibility": 0
          }
        ]
      }
    ],
    "trend": [
      {
        "run_id": "9",
        "finished_at": "2026-10-07T09:12:40.020Z",
        "mode": "knowledge",
        "visibility": 0.15,
        "by_model": [
          {
            "model": "gpt-6-astra",
            "visibility": 0.2
          },
          {
            "model": "claude-sonnet-5-5",
            "visibility": 0.1
          }
        ]
      },
      {
        "run_id": "12",
        "finished_at": "2026-11-07T09:01:37.874Z",
        "mode": "knowledge",
        "visibility": 0.2333,
        "by_model": [
          {
            "model": "gpt-6-astra",
            "visibility": 0.3
          },
          {
            "model": "claude-sonnet-5-5",
            "visibility": 0.1
          }
        ]
      }
    ]
  }
}
```

> Rates are numbers from 0 to 1. A metric is `null` when there's nothing to count, such as stability with one sample.

## List the names AI answers give

`GET https://autoranko.com/api/public/v1/sites/{id}/geo/competitors`

Scope: `geo:read`.

Ranks every company, brand and product the latest finished run of a mode names, your own brand included (`brand: true`), by how many answers name it, with its share of voice and average position. Names come from a separate extraction call that reads the finished answers; hide or merge names in Dashboard → AI Visibility → Competitors.

These are names the models wrote. In `knowledge` mode they reflect training data, not who ranks or sells today.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Site ID, from `GET /sites`. |
| `mode` | query | string | no | The mode to report. Without it: the mode of the latest finished run. One of: knowledge, search. |
| `limit` | query | integer | no | How many names to return. Values outside 1–200 are clamped. Default: 50. |

### Response 200

The leaderboard.

- `site_id` (string): ID of the site.
- `mode` (string, one of knowledge | search): How the answers behind this number were produced: `knowledge` (the bare question through the API, no web search) or `search` (the model ran web searches and the provider returned the traces). The two are never mixed.
- `disclaimer` (string): The label for these numbers.
- `run_id` (string, nullable): The run they come from, or `null` before the first finished run.
- `answers_considered` (integer): Answers read.
- `competitors` (object[]): Names, most named first.
  - `name` (string): The name as answers write it (after your merge rules).
  - `domain` (string, nullable): Its domain when an answer wrote one, else `null`.
  - `brand` (boolean): `true` for your own brand.
  - `mode` (string, one of knowledge | search): How the answers behind this number were produced: `knowledge` (the bare question through the API, no web search) or `search` (the model ran web searches and the provider returned the traces). The two are never mixed.
  - `answers` (integer): Answers that name it.
  - `answer_share` (number, nullable): `answers` / answers considered. A number from 0 to 1, or `null` with nothing to count.
  - `share_of_voice` (number, nullable): Its mentions / all name mentions. A number from 0 to 1, or `null` with nothing to count.
  - `avg_rank` (number, nullable): Average position where it is named.
  - `models` (string[]): Models whose answers name it.
- `hidden` (string[]): Names you hid (lowercase).

### Errors

- 400 `invalid_body`: `mode` isn't `knowledge` or `search` (`mode must be one of: knowledge, search.`).
- 401 `missing_token`: The `Authorization: Bearer …` header is missing.
- 401 `invalid_token`: The token is malformed, unknown or revoked, or an OAuth token issued for another resource.
- 401 `token_expired`: The API key passed its expiry date, or the OAuth access token is more than an hour old.
- 403 `insufficient_scope`: The API key or OAuth connection doesn't have the `geo:read` scope.
- 404 `not_found`: No site with this `id` belongs to your account (`Site not found.`).
- 429 `rate_limited`: The key or OAuth connection made more than 120 requests in the last 60 seconds.

### Example request

```bash
curl "https://autoranko.com/api/public/v1/sites/1/geo/competitors?limit=10" \
  -H "Authorization: Bearer $AUTORANKO_TOKEN"
```

### Example response (200) — illustrative

```json
{
  "site_id": "1",
  "mode": "knowledge",
  "disclaimer": "Model knowledge: what GPT-6 Astra / Claude Sonnet 5.5 answer from training data via API, without web search. ChatGPT.com or Claude.ai with browsing may answer differently.",
  "run_id": "12",
  "answers_considered": 30,
  "competitors": [
    {
      "name": "Lone Star Lawn & Irrigation",
      "domain": null,
      "brand": false,
      "mode": "knowledge",
      "answers": 14,
      "answer_share": 0.4667,
      "share_of_voice": 0.2258,
      "avg_rank": 1.4,
      "models": [
        "gpt-6-astra",
        "claude-sonnet-5-5"
      ]
    },
    {
      "name": "Hill Country Irrigation",
      "domain": null,
      "brand": false,
      "mode": "knowledge",
      "answers": 9,
      "answer_share": 0.3,
      "share_of_voice": 0.1452,
      "avg_rank": 2.2,
      "models": [
        "gpt-6-astra",
        "claude-sonnet-5-5"
      ]
    },
    {
      "name": "Greenfield Irrigation",
      "domain": "demo.autoranko.com",
      "brand": true,
      "mode": "knowledge",
      "answers": 7,
      "answer_share": 0.2333,
      "share_of_voice": 0.1129,
      "avg_rank": 2.57,
      "models": [
        "gpt-6-astra",
        "claude-sonnet-5-5"
      ]
    }
  ],
  "hidden": []
}
```

## Get AI-assistant traffic (GA4)

`GET https://autoranko.com/api/public/v1/sites/{id}/geo/ai-traffic`

Scope: `geo:read`.

Returns the sessions AI assistants sent to the site over the last full days, from the site's own Google Analytics 4 property: per assistant, per week and per landing page, with their share of all sessions. Measured in your GA4. Undercounts assistant visits that arrive without a referrer.

It needs Google Analytics connected (Dashboard → AI Visibility → AI traffic → Connect Google Analytics, a read-only grant) and a GA4 property chosen for the site. Reports are cached for 6 hours.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Site ID, from `GET /sites`. |
| `days` | query | integer | no | Full days to cover, ending yesterday. Values outside 7–90 are clamped. Default: 28. |

### Response 200

The report.

- `traffic` (object): AI-assistant sessions.
  - `site_id` (string): ID of the site.
  - `property` (string): The GA4 property the numbers come from (`properties/…`).
  - `days` (integer): Full days covered, ending yesterday in the property's time zone (7 to 90).
  - `note` (string): Always: `Measured in your GA4. Undercounts assistant visits that arrive without a referrer.`
  - `fetched_at` (string): When Autoranko read the report from GA4 (reports are cached for 6 hours).
  - `totals` (object): Totals over the period.
    - `ai_sessions` (integer): Sessions whose source is an AI assistant.
    - `ai_engaged_sessions` (integer): Engaged sessions among them (GA4's definition).
    - `ai_key_events` (integer): Key events in those sessions.
    - `all_sessions` (integer): All sessions of the property, for comparison.
    - `ai_share` (number, nullable): `ai_sessions` / `all_sessions`. A number from 0 to 1, or `null` with nothing to count.
  - `assistants` (object[]): Sessions per assistant (ChatGPT, Perplexity, Claude, Gemini, Copilot, You.com, Meta AI, DeepSeek, Grok, Poe), most first.
    - `assistant` (string): The assistant.
    - `sessions` (integer): Sessions.
    - `engaged_sessions` (integer): Engaged sessions.
    - `key_events` (integer): Key events.
  - `weekly` (object[]): AI sessions per week (weeks start on Monday).
    - `week_start` (string): Monday of the week, `YYYY-MM-DD`.
    - `total` (integer): AI sessions that week.
    - `by_assistant` (object): Sessions that week per assistant, keyed by assistant name.
  - `top_landing_pages` (object[]): Pages AI assistants sent visitors to, most first (at most 25).
    - `page` (string): Landing page path and query string, as GA4 reports it.
    - `sessions` (integer): Sessions.
    - `engaged_sessions` (integer): Engaged sessions.
    - `key_events` (integer): Key events.

### Errors

- 401 `missing_token`: The `Authorization: Bearer …` header is missing.
- 401 `invalid_token`: The token is malformed, unknown or revoked, or an OAuth token issued for another resource.
- 401 `token_expired`: The API key passed its expiry date, or the OAuth access token is more than an hour old.
- 403 `insufficient_scope`: The API key or OAuth connection doesn't have the `geo:read` scope.
- 404 `not_found`: No site with this `id` belongs to your account (`Site not found.`).
- 409 `invalid_state`: Google sign-in isn't configured on the server (`Google sign-in isn't configured on this server yet.`).
- 409 `invalid_state`: Google Analytics isn't connected, or access was revoked (`Connect Google Analytics in Dashboard → AI Visibility first.`).
- 409 `invalid_state`: No GA4 property is chosen for the site (`Choose a GA4 property in Dashboard → AI Visibility → AI traffic first.`).
- 429 `rate_limited`: The key or OAuth connection made more than 120 requests in the last 60 seconds.
- 502 `upstream_error`: Google Analytics failed (`Google Analytics request failed, please retry.`) or refused the request; `message` carries Google's reason when it gives one.

### Example request

```bash
curl "https://autoranko.com/api/public/v1/sites/1/geo/ai-traffic?days=28" \
  -H "Authorization: Bearer $AUTORANKO_TOKEN"
```

### Example response (200) — illustrative

```json
{
  "traffic": {
    "site_id": "1",
    "property": "properties/312345678",
    "days": 28,
    "note": "Measured in your GA4. Undercounts assistant visits that arrive without a referrer.",
    "fetched_at": "2026-11-07T07:45:10.331Z",
    "totals": {
      "ai_sessions": 142,
      "ai_engaged_sessions": 97,
      "ai_key_events": 9,
      "all_sessions": 6810,
      "ai_share": 0.0209
    },
    "assistants": [
      {
        "assistant": "ChatGPT",
        "sessions": 118,
        "engaged_sessions": 82,
        "key_events": 8
      },
      {
        "assistant": "Perplexity",
        "sessions": 15,
        "engaged_sessions": 9,
        "key_events": 1
      },
      {
        "assistant": "Claude",
        "sessions": 6,
        "engaged_sessions": 4,
        "key_events": 0
      },
      {
        "assistant": "Gemini",
        "sessions": 3,
        "engaged_sessions": 2,
        "key_events": 0
      }
    ],
    "weekly": [
      {
        "week_start": "2026-10-12",
        "total": 29,
        "by_assistant": {
          "ChatGPT": 25,
          "Perplexity": 4
        }
      },
      {
        "week_start": "2026-10-19",
        "total": 37,
        "by_assistant": {
          "ChatGPT": 30,
          "Perplexity": 4,
          "Claude": 3
        }
      }
    ],
    "top_landing_pages": [
      {
        "page": "/drip-irrigation-vs-sprinklers/",
        "sessions": 61,
        "engaged_sessions": 45,
        "key_events": 5
      },
      {
        "page": "/",
        "sessions": 38,
        "engaged_sessions": 24,
        "key_events": 3
      }
    ]
  }
}
```
