autoranko

API reference

AI visibility

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

8 endpointsBase URL https://autoranko.com/api/public/v1Every request needs a bearer token

Model knowledge unless the mode says search

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. Each tracked prompt is sent to each model as the only user message: no system prompt, no brand, no instruction to list companies or URLs. Brands are identified afterwards in a separate call. A separate model call reads up to five finished answers at a time and lists the companies, brands and products each one names, in order of appearance. Your brand, aliases and domains are first matched exactly in the text; the extraction only adds the other names and their order. In knowledge mode, URLs inside answers are "URLs the model wrote (unverified)", never sources.

List tracked prompts

GEThttps://autoranko.com/api/public/v1/sites/{id}/geo/promptsgeo: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.

Request

Path parameters
Query parameters
  • intentstringOptional
    Only prompts with this intent. An unknown value is rejected with 400 invalid_body.

    One ofunderstandingbenefitscomparisonqualityselection

    Example
    selection
  • activebooleanOptional
    true: only the active prompts that runs include.
    Example
    true
curl https://autoranko.com/api/public/v1/sites/1/geo/prompts \
  -H "Authorization: Bearer $AUTORANKO_TOKEN"

Response

200OKThe site's prompts and the account allowance.

Response bodyapplication/json
  • promptsarray of objects
    Prompts, active first.
    prompts items(8)GeoPrompt
    • idstring
      Prompt ID: a 64-bit integer serialized as a string.
    • site_idstring
      ID of the site the prompt is tracked for.
    • textstring
      The buyer question, exactly as sent to the models (3 to 300 characters). It never names the brand.
    • intentstring
      What the buyer wants: understanding, benefits, comparison, quality or selection.

      One ofunderstandingbenefitscomparisonqualityselection

    • sourcestring
      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).

      One ofgeneratedmanualimportapi

    • languagestring
      Language code of the market it was written for, or an empty string.
    • activeboolean
      true when runs include it. Active prompts count against the account's allowance; inactive ones wait.
    • created_atstring (date-time)
      When the prompt was added.
  • allowanceobject
    The account's AI-visibility allowance.
    allowance keys(9)GeoAllowance
    • planstring
      The account's plan.

      One offreestarterpro

    • scopestring
      Always account: these allowances are shared by all of the account's sites.

      One ofaccount

    • active_prompts_usedinteger
      Active prompts across all of the account's sites.
    • active_prompts_limitinteger
      Active prompts the plan allows (free 5, starter 20, pro 50).
    • manual_runs_usedinteger
      Manual runs started this calendar month (UTC) across the account's sites, from the dashboard and this API.
    • manual_runs_limitinteger
      Manual runs the plan allows per calendar month. Scheduled runs don't count.
    • models_limitinteger
      Model families (GPT, Claude) a run can track.
    • samples_limitinteger
      Samples per prompt and model: repeats that measure how stable the answers are.
    • cadencestring
      How often scheduled runs happen on this plan.

      One ofmonthlyweekly

Example

Tracked prompts

GET/sites/1/geo/promptsIllustrative

Response · 200 OK
{
  "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"
  }
}

Shortened to three prompts.

Errors

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

Add prompts

POSThttps://autoranko.com/api/public/v1/sites/{id}/geo/promptsgeo:write

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

Request

Path parameters
Body parametersapplication/json
  • promptsarray of stringsRequired
    The questions, as a buyer would type them into an AI assistant: 1 to 50 strings.
    Max items
    50
    Example
    ["How much does a smart irrigation controller save on water bills?","Is Greenfield Irrigation any good?"]
  • intentstringOptional
    One intent for every prompt in the request. Omit it to label each prompt from its wording.

    One ofunderstandingbenefitscomparisonqualityselection

    Example
    benefits

Optional header Idempotency-Key: retrying with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of running the request twice. Idempotency keys

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?"
    ]
  }'

Response

201CreatedAt least one prompt was added.

Response bodyapplication/json
  • addedarray of objects
    The prompts added (active while the allowance lasted).
    added items(8)GeoPrompt
    • idstring
      Prompt ID: a 64-bit integer serialized as a string.
    • site_idstring
      ID of the site the prompt is tracked for.
    • textstring
      The buyer question, exactly as sent to the models (3 to 300 characters). It never names the brand.
    • intentstring
      What the buyer wants: understanding, benefits, comparison, quality or selection.

      One ofunderstandingbenefitscomparisonqualityselection

    • sourcestring
      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).

      One ofgeneratedmanualimportapi

    • languagestring
      Language code of the market it was written for, or an empty string.
    • activeboolean
      true when runs include it. Active prompts count against the account's allowance; inactive ones wait.
    • created_atstring (date-time)
      When the prompt was added.
  • rejectedarray of objects
    Prompts that weren't added, with why.
    rejected items(2)
    • textstring
      The prompt as sent.
    • reasonstring
      Why it wasn't added.
  • allowanceobject
    The allowance after the change.
    allowance keys(9)GeoAllowance
    • planstring
      The account's plan.

      One offreestarterpro

    • scopestring
      Always account: these allowances are shared by all of the account's sites.

      One ofaccount

    • active_prompts_usedinteger
      Active prompts across all of the account's sites.
    • active_prompts_limitinteger
      Active prompts the plan allows (free 5, starter 20, pro 50).
    • manual_runs_usedinteger
      Manual runs started this calendar month (UTC) across the account's sites, from the dashboard and this API.
    • manual_runs_limitinteger
      Manual runs the plan allows per calendar month. Scheduled runs don't count.
    • models_limitinteger
      Model families (GPT, Claude) a run can track.
    • samples_limitinteger
      Samples per prompt and model: repeats that measure how stable the answers are.
    • cadencestring
      How often scheduled runs happen on this plan.

      One ofmonthlyweekly

Examples

POST/sites/1/geo/promptsIllustrative

Request body
{
  "prompts": [
    "How much does a smart irrigation controller save on water bills?",
    "Is Greenfield Irrigation any good?"
  ]
}
Response · 201 Created
{
  "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"
  }
}

Errors

ErrorWhen
400invalid_bodyThe body isn't valid JSON (Invalid JSON body.).
400invalid_bodyprompts is missing, empty, longer than 50 items or not all strings (prompts must be a non-empty array of strings (at most 50).).
400invalid_bodyintent isn't one of the five intents (intent must be one of: understanding, benefits, comparison, quality, selection.).
400invalid_bodyNo prompt could be added (None of the prompts could be added. …, followed by the first reason).
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked, or an OAuth token issued for another resource.
401token_expiredThe API key passed its expiry date, or the OAuth access token is more than an hour old.
403insufficient_scopeThe API key or OAuth connection doesn't have the geo:write scope.
404not_foundNo site with this id belongs to your account (Site not found.).
409idempotency_conflictThe Idempotency-Key was already used for a different request in the last 24 hours.
409idempotency_in_progressA request with the same Idempotency-Key is still running.
429rate_limitedThe key or OAuth connection made more than 120 requests in the last 60 seconds.
429plan_limitThe 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.).

Start a run

POSThttps://autoranko.com/api/public/v1/sites/{id}/geo/runsgeo:write

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.

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

Request

Path parameters

Optional header Idempotency-Key: retrying with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of running the request twice. Idempotency keys

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

Response

201CreatedThe run was created in queued.

Response bodyapplication/json
  • runobject
    The new run.
    run keys(18)GeoRun
    • idstring
      Run ID: a 64-bit integer serialized as a string.
    • site_idstring
      ID of the site.
    • triggerstring
      What started it: the schedule (cron), the dashboard (manual) or this API (api).

      One ofcronmanualapi

    • modestring
      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.

      One ofknowledgesearch

    • statusstring
      queued and running while answers come in; then done (every answer received), partial (some failed: see model_stats) or failed (none received).

      One ofqueuedrunningdonepartialfailed

    • modelsarray of strings
      The tracked models, one per family.
    • samplesinteger
      Times each prompt was asked of each model.
    • prompt_countinteger
      Prompts in the run.
    • expectedinteger
      Answers the run asks for: prompt_count × models × samples.
    • completedinteger
      Answers received so far.
    • failedinteger
      Answers that failed so far.
    • visibilitynumber or null
      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_statsarray of objects
      Per-model results, once the run has finished (empty before).
      model_stats items(9)GeoModelStat
      • modelstring
        The tracked model, such as gpt-6-astra or claude-sonnet-5-5. Answers are attributed to the model asked, never to a fallback.
      • providerstring or null
        Which service answered for it, or null if none did.

        One ofkieopenaianthropicdataforseo

      • modestring
        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.

        One ofknowledgesearch

      • completedinteger
        Answers received.
      • failedinteger
        Answers that failed (the model or its relay was unavailable, timed out, or returned nothing).
      • mentionedinteger
        Received answers that name the brand, an alias or one of its domains.
      • visibilitynumber or null
        mentioned / completed. A number from 0 to 1, or null with nothing to count.
      • avg_mention_ranknumber or null
        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_errorstring or null
        The last failure for this model in the run, or null.
    • notesstring or null
      Why the run differs from the settings (for example, live search requested but unavailable), or null.
    • errorstring or null
      Why a failed run failed, or null.
    • created_atstring (date-time)
      When the run was started.
    • started_atstring (date-time) or null
      When the first answer was requested, or null.
    • finished_atstring (date-time) or null
      When the run finished, or null while it's open.

Examples

POST/sites/1/geo/runsIllustrative

Response · 201 Created
{
  "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
  }
}

Errors

ErrorWhen
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked, or an OAuth token issued for another resource.
401token_expiredThe API key passed its expiry date, or the OAuth access token is more than an hour old.
403insufficient_scopeThe API key or OAuth connection doesn't have the geo:write scope.
404not_foundNo site with this id belongs to your account (Site not found.).
409invalid_stateA run is already queued or running for the site (An AI-visibility run is already in progress for this site.).
409invalid_stateThe site has no active prompt (Add prompts before starting a run.).
409idempotency_conflictThe Idempotency-Key was already used for a different request in the last 24 hours.
409idempotency_in_progressA request with the same Idempotency-Key is still running.
429rate_limitedThe key or OAuth connection made more than 120 requests in the last 60 seconds.
429plan_limitThe 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.).

List runs

GEThttps://autoranko.com/api/public/v1/sites/{id}/geo/runsgeo: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.

Request

Path parameters
Query parameters
  • limitintegerOptional
    How many of the newest runs to return. Values outside 1–100 are clamped.
    Default
    20
    Range
    1–100
    Example
    20
curl "https://autoranko.com/api/public/v1/sites/1/geo/runs?limit=10" \
  -H "Authorization: Bearer $AUTORANKO_TOKEN"

Response

200OKThe newest runs.

Response bodyapplication/json
  • runsarray of objects
    Runs, newest first.
    runs items(18)GeoRun
    • idstring
      Run ID: a 64-bit integer serialized as a string.
    • site_idstring
      ID of the site.
    • triggerstring
      What started it: the schedule (cron), the dashboard (manual) or this API (api).

      One ofcronmanualapi

    • modestring
      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.

      One ofknowledgesearch

    • statusstring
      queued and running while answers come in; then done (every answer received), partial (some failed: see model_stats) or failed (none received).

      One ofqueuedrunningdonepartialfailed

    • modelsarray of strings
      The tracked models, one per family.
    • samplesinteger
      Times each prompt was asked of each model.
    • prompt_countinteger
      Prompts in the run.
    • expectedinteger
      Answers the run asks for: prompt_count × models × samples.
    • completedinteger
      Answers received so far.
    • failedinteger
      Answers that failed so far.
    • visibilitynumber or null
      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_statsarray of objects
      Per-model results, once the run has finished (empty before).
      model_stats items(9)GeoModelStat
      • modelstring
        The tracked model, such as gpt-6-astra or claude-sonnet-5-5. Answers are attributed to the model asked, never to a fallback.
      • providerstring or null
        Which service answered for it, or null if none did.

        One ofkieopenaianthropicdataforseo

      • modestring
        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.

        One ofknowledgesearch

      • completedinteger
        Answers received.
      • failedinteger
        Answers that failed (the model or its relay was unavailable, timed out, or returned nothing).
      • mentionedinteger
        Received answers that name the brand, an alias or one of its domains.
      • visibilitynumber or null
        mentioned / completed. A number from 0 to 1, or null with nothing to count.
      • avg_mention_ranknumber or null
        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_errorstring or null
        The last failure for this model in the run, or null.
    • notesstring or null
      Why the run differs from the settings (for example, live search requested but unavailable), or null.
    • errorstring or null
      Why a failed run failed, or null.
    • created_atstring (date-time)
      When the run was started.
    • started_atstring (date-time) or null
      When the first answer was requested, or null.
    • finished_atstring (date-time) or null
      When the run finished, or null while it's open.

Example

Recent runs

GET/sites/1/geo/runs?limit=1Illustrative

Response · 200 OK
{
  "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"
    }
  ]
}

Errors

ErrorWhen
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked, or an OAuth token issued for another resource.
401token_expiredThe API key passed its expiry date, or the OAuth access token is more than an hour old.
403insufficient_scopeThe API key or OAuth connection doesn't have the geo:read scope.
404not_foundNo site with this id belongs to your account (Site not found.).
429rate_limitedThe key or OAuth connection made more than 120 requests in the last 60 seconds.

Get a run with its answers

GEThttps://autoranko.com/api/public/v1/geo/runs/{id}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.

Request

Path parameters
Query parameters
  • limitintegerOptional
    Answers per page. Values outside 1–500 are clamped.
    Default
    100
    Range
    1–500
    Example
    100
  • offsetintegerOptional
    Answers to skip, for pagination.
    Default
    0
    Minimum
    0
    Example
    0
  • modelstringOptional
    Only this model's answers, such as gpt-6-astra.
    Example
    gpt-6-astra
  • statusstringOptional
    Only answers in this status. An unknown value is rejected with 400 invalid_body.

    One ofpendingrunningokfailed

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

Response

200OKThe run and one page of its answers.

Response bodyapplication/json
  • runobject
    The run.
    run keys(18)GeoRun
    • idstring
      Run ID: a 64-bit integer serialized as a string.
    • site_idstring
      ID of the site.
    • triggerstring
      What started it: the schedule (cron), the dashboard (manual) or this API (api).

      One ofcronmanualapi

    • modestring
      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.

      One ofknowledgesearch

    • statusstring
      queued and running while answers come in; then done (every answer received), partial (some failed: see model_stats) or failed (none received).

      One ofqueuedrunningdonepartialfailed

    • modelsarray of strings
      The tracked models, one per family.
    • samplesinteger
      Times each prompt was asked of each model.
    • prompt_countinteger
      Prompts in the run.
    • expectedinteger
      Answers the run asks for: prompt_count × models × samples.
    • completedinteger
      Answers received so far.
    • failedinteger
      Answers that failed so far.
    • visibilitynumber or null
      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_statsarray of objects
      Per-model results, once the run has finished (empty before).
      model_stats items(9)GeoModelStat
      • modelstring
        The tracked model, such as gpt-6-astra or claude-sonnet-5-5. Answers are attributed to the model asked, never to a fallback.
      • providerstring or null
        Which service answered for it, or null if none did.

        One ofkieopenaianthropicdataforseo

      • modestring
        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.

        One ofknowledgesearch

      • completedinteger
        Answers received.
      • failedinteger
        Answers that failed (the model or its relay was unavailable, timed out, or returned nothing).
      • mentionedinteger
        Received answers that name the brand, an alias or one of its domains.
      • visibilitynumber or null
        mentioned / completed. A number from 0 to 1, or null with nothing to count.
      • avg_mention_ranknumber or null
        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_errorstring or null
        The last failure for this model in the run, or null.
    • notesstring or null
      Why the run differs from the settings (for example, live search requested but unavailable), or null.
    • errorstring or null
      Why a failed run failed, or null.
    • created_atstring (date-time)
      When the run was started.
    • started_atstring (date-time) or null
      When the first answer was requested, or null.
    • finished_atstring (date-time) or null
      When the run finished, or null while it's open.
  • answersarray of objects
    One page of answers.
    answers items(23)GeoAnswer
    • idstring
      Answer ID: a 64-bit integer serialized as a string.
    • run_idstring
      ID of the run.
    • prompt_idstring or null
      ID of the prompt, or null if the prompt was deleted.
    • prompt_textstring
      The exact text that was sent, as it was when the run started.
    • intentstring
      The prompt's intent at the time.

      One ofunderstandingbenefitscomparisonqualityselection

    • modelstring
      The model asked. The answer is attributed to it and nothing else.
    • model_servedstring or null
      The model the provider reported it ran, or null before an answer.
    • providerstring
      The service that answered.

      One ofkieopenaianthropicdataforseo

    • modestring
      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.

      One ofknowledgesearch

    • sampleinteger
      Which repeat of this prompt and model (1 to the run's samples).
    • statusstring
      pending and running until answered, then ok or failed.

      One ofpendingrunningokfailed

    • answerstring or null
      The full answer text, or null until there is one.
    • errorstring or null
      Why the answer failed, or null.
    • mentionedboolean or null
      Whether the answer names the brand, an alias or one of its domains (exact match). null unless status is ok.
    • mention_rankinteger or null
      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_mentionedboolean or null
      Whether one of the site's domains appears in the answer. null unless status is ok.
    • entitiesarray of objects
      Every company, brand or product the answer names, in order (read by a separate extraction call).
      entities items(4)GeoEntity
      • namestring
        A company, brand or product the answer names, as written (your brand under its brand name).
      • domainstring or null
        Its domain when the answer writes one, else null.
      • rankinteger
        Order of first appearance in the answer (1 = first).
      • brandboolean
        true for your brand (matched exactly on its name, aliases or domains).
    • urls_writtenarray of objects
      URLs written in the answer text. In knowledge mode these are URLs the model wrote from memory: unverified, never sources.
      urls_written items(3)GeoLink
      • urlstring (uri)
        The URL.
      • domainstring
        Its registrable domain, such as example.co.uk.
      • titlestringOptional
        The page title the provider returned (citations only).
    • searchesarray of strings
      Search queries: observed in the provider's traces (searches_kind: observed) or what the model said it would search when asked separately (predicted).
    • searches_kindstring
      observed (tool traces), predicted (asked separately; not observed) or none.

      One ofobservedpredictednone

    • citationsarray of objects
      Sources the provider returned with a search answer. Always empty in knowledge mode.
      citations items(3)GeoLink
      • urlstring (uri)
        The URL.
      • domainstring
        Its registrable domain, such as example.co.uk.
      • titlestringOptional
        The page title the provider returned (citations only).
    • created_atstring (date-time)
      When the answer was queued.
    • answered_atstring (date-time) or null
      When it was answered or failed, or null.
  • limitinteger
    The page size applied.
  • offsetinteger
    The offset applied.

Examples

GET/geo/runs/12?limit=2Illustrative

Response · 200 OK
{
  "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
}

Two answers to the same prompt: GPT-6 Astra answered; the Claude relay failed, and the failure counts for Claude.

Errors

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

Get visibility metrics

GEThttps://autoranko.com/api/public/v1/sites/{id}/geo/statsgeo: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.

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

Request

Path parameters
Query parameters
  • modestringOptional
    The mode to report. Without it: the mode of the latest finished run. An unknown value is rejected with 400 invalid_body.

    One ofknowledgesearch

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

Response

200OKThe metrics.

Response bodyapplication/json
  • statsobject
    AI-visibility metrics.
    stats keys(14)GeoStats
    • site_idstring
      ID of the site.
    • modestring
      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.

      One ofknowledgesearch

    • disclaimerstring
      The label that goes with every number of this mode, naming the tracked models. Show it next to them.
    • modes_availablearray of strings
      Modes with at least one finished run.

      One ofknowledgesearch

    • runobject or null
      The latest finished run of this mode, which the metrics below describe, or null before the first one.
      run keys(18)GeoRun
      • idstring
        Run ID: a 64-bit integer serialized as a string.
      • site_idstring
        ID of the site.
      • triggerstring
        What started it: the schedule (cron), the dashboard (manual) or this API (api).

        One ofcronmanualapi

      • modestring
        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.

        One ofknowledgesearch

      • statusstring
        queued and running while answers come in; then done (every answer received), partial (some failed: see model_stats) or failed (none received).

        One ofqueuedrunningdonepartialfailed

      • modelsarray of strings
        The tracked models, one per family.
      • samplesinteger
        Times each prompt was asked of each model.
      • prompt_countinteger
        Prompts in the run.
      • expectedinteger
        Answers the run asks for: prompt_count × models × samples.
      • completedinteger
        Answers received so far.
      • failedinteger
        Answers that failed so far.
      • visibilitynumber or null
        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_statsarray of objects
        Per-model results, once the run has finished (empty before).
        model_stats items(9)GeoModelStat
        • modelstring
          The tracked model, such as gpt-6-astra or claude-sonnet-5-5. Answers are attributed to the model asked, never to a fallback.
        • providerstring or null
          Which service answered for it, or null if none did.

          One ofkieopenaianthropicdataforseo

        • modestring
          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.

          One ofknowledgesearch

        • completedinteger
          Answers received.
        • failedinteger
          Answers that failed (the model or its relay was unavailable, timed out, or returned nothing).
        • mentionedinteger
          Received answers that name the brand, an alias or one of its domains.
        • visibilitynumber or null
          mentioned / completed. A number from 0 to 1, or null with nothing to count.
        • avg_mention_ranknumber or null
          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_errorstring or null
          The last failure for this model in the run, or null.
      • notesstring or null
        Why the run differs from the settings (for example, live search requested but unavailable), or null.
      • errorstring or null
        Why a failed run failed, or null.
      • created_atstring (date-time)
        When the run was started.
      • started_atstring (date-time) or null
        When the first answer was requested, or null.
      • finished_atstring (date-time) or null
        When the run finished, or null while it's open.
    • visibilitynumber or null
      Share of the run's answers that name the brand. A number from 0 to 1, or null with nothing to count.
    • avg_mention_ranknumber or null
      Average position of the brand where it is named, or null.
    • share_of_voicenumber or null
      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.
    • stabilitynumber or null
      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.
    • samplesinteger
      Samples per prompt and model in the run.
    • by_modelarray of objects
      The same metrics per tracked model.
      by_model items(8)
      • modelstring
        The model.
      • modestring
        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.

        One ofknowledgesearch

      • completedinteger
        Answers received.
      • mentionedinteger
        Answers that name the brand.
      • visibilitynumber or null
        mentioned / completed. A number from 0 to 1, or null with nothing to count.
      • avg_mention_ranknumber or null
        Average position where named, or null.
      • share_of_voicenumber or null
        Share of voice in this model's answers. A number from 0 to 1, or null with nothing to count.
      • stabilitynumber or null
        Stability of this model's answers. A number from 0 to 1, or null with nothing to count.
    • by_intentarray of objects
      Visibility per prompt intent.
      by_intent items(5)
      • intentstring
        The intent.

        One ofunderstandingbenefitscomparisonqualityselection

      • modestring
        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.

        One ofknowledgesearch

      • completedinteger
        Answers received.
      • mentionedinteger
        Answers that name the brand.
      • visibilitynumber or null
        mentioned / completed. A number from 0 to 1, or null with nothing to count.
    • by_promptarray of objects
      Visibility per prompt, least visible first: the prompts to write content for.
      by_prompt items(8)
      • prompt_idstring or null
        ID of the prompt, or null.
      • textstring
        The prompt as sent.
      • intentstring
        Its intent.

        One ofunderstandingbenefitscomparisonqualityselection

      • modestring
        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.

        One ofknowledgesearch

      • completedinteger
        Answers received.
      • mentionedinteger
        Answers that name the brand.
      • visibilitynumber or null
        mentioned / completed. A number from 0 to 1, or null with nothing to count.
      • by_modelarray of objects
        Per model.
        by_model items(4)
        • modelstring
          The model.
        • completedinteger
          Answers received.
        • mentionedinteger
          Answers that name the brand.
        • visibilitynumber or null
          mentioned / completed. A number from 0 to 1, or null with nothing to count.
    • trendarray of objects
      Finished runs of the same mode, oldest first (at most 26). Knowledge and search runs never share a trend.
      trend items(5)
      • run_idstring
        ID of the run.
      • finished_atstring (date-time) or null
        When it finished.
      • modestring
        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.

        One ofknowledgesearch

      • visibilitynumber or null
        The run's visibility. A number from 0 to 1, or null with nothing to count.
      • by_modelarray of objects
        Per model.
        by_model items(2)
        • modelstring
          The model.
        • visibilitynumber or null
          The model's visibility in that run. A number from 0 to 1, or null with nothing to count.

Example

Model-knowledge metrics

GET/sites/1/geo/statsIllustrative

Response · 200 OK
{
  "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
          }
        ]
      }
    ]
  }
}

Lists shortened.

Errors

ErrorWhen
400invalid_bodymode isn't knowledge or search (mode must be one of: knowledge, search.).
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked, or an OAuth token issued for another resource.
401token_expiredThe API key passed its expiry date, or the OAuth access token is more than an hour old.
403insufficient_scopeThe API key or OAuth connection doesn't have the geo:read scope.
404not_foundNo site with this id belongs to your account (Site not found.).
429rate_limitedThe key or OAuth connection made more than 120 requests in the last 60 seconds.

List the names AI answers give

GEThttps://autoranko.com/api/public/v1/sites/{id}/geo/competitorsgeo: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.

Request

Path parameters
Query parameters
  • modestringOptional
    The mode to report. Without it: the mode of the latest finished run.

    One ofknowledgesearch

    Example
    knowledge
  • limitintegerOptional
    How many names to return. Values outside 1–200 are clamped.
    Default
    50
    Range
    1–200
    Example
    20
curl "https://autoranko.com/api/public/v1/sites/1/geo/competitors?limit=10" \
  -H "Authorization: Bearer $AUTORANKO_TOKEN"

Response

200OKThe leaderboard.

Response bodyapplication/json
  • site_idstring
    ID of the site.
  • modestring
    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.

    One ofknowledgesearch

  • disclaimerstring
    The label for these numbers.
  • run_idstring or null
    The run they come from, or null before the first finished run.
  • answers_consideredinteger
    Answers read.
  • competitorsarray of objects
    Names, most named first.
    competitors items(9)GeoCompetitor
    • namestring
      The name as answers write it (after your merge rules).
    • domainstring or null
      Its domain when an answer wrote one, else null.
    • brandboolean
      true for your own brand.
    • modestring
      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.

      One ofknowledgesearch

    • answersinteger
      Answers that name it.
    • answer_sharenumber or null
      answers / answers considered. A number from 0 to 1, or null with nothing to count.
    • share_of_voicenumber or null
      Its mentions / all name mentions. A number from 0 to 1, or null with nothing to count.
    • avg_ranknumber or null
      Average position where it is named.
    • modelsarray of strings
      Models whose answers name it.
  • hiddenarray of strings
    Names you hid (lowercase).

Example

Leaderboard

GET/sites/1/geo/competitors?limit=3Illustrative

Response · 200 OK
{
  "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": []
}

Errors

ErrorWhen
400invalid_bodymode isn't knowledge or search (mode must be one of: knowledge, search.).
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked, or an OAuth token issued for another resource.
401token_expiredThe API key passed its expiry date, or the OAuth access token is more than an hour old.
403insufficient_scopeThe API key or OAuth connection doesn't have the geo:read scope.
404not_foundNo site with this id belongs to your account (Site not found.).
429rate_limitedThe key or OAuth connection made more than 120 requests in the last 60 seconds.

Get AI-assistant traffic (GA4)

GEThttps://autoranko.com/api/public/v1/sites/{id}/geo/ai-trafficgeo: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.

Request

Path parameters
Query parameters
  • daysintegerOptional
    Full days to cover, ending yesterday. Values outside 7–90 are clamped.
    Default
    28
    Range
    7–90
    Example
    28
curl "https://autoranko.com/api/public/v1/sites/1/geo/ai-traffic?days=28" \
  -H "Authorization: Bearer $AUTORANKO_TOKEN"

Response

200OKThe report.

Response bodyapplication/json
  • trafficobject
    AI-assistant sessions.
    traffic keys(9)GeoTraffic
    • site_idstring
      ID of the site.
    • propertystring
      The GA4 property the numbers come from (properties/…).
    • daysinteger
      Full days covered, ending yesterday in the property's time zone (7 to 90).
    • notestring
      Always: Measured in your GA4. Undercounts assistant visits that arrive without a referrer.
    • fetched_atstring (date-time)
      When Autoranko read the report from GA4 (reports are cached for 6 hours).
    • totalsobject
      Totals over the period.
      totals keys(5)
      • ai_sessionsinteger
        Sessions whose source is an AI assistant.
      • ai_engaged_sessionsinteger
        Engaged sessions among them (GA4's definition).
      • ai_key_eventsinteger
        Key events in those sessions.
      • all_sessionsinteger
        All sessions of the property, for comparison.
      • ai_sharenumber or null
        ai_sessions / all_sessions. A number from 0 to 1, or null with nothing to count.
    • assistantsarray of objects
      Sessions per assistant (ChatGPT, Perplexity, Claude, Gemini, Copilot, You.com, Meta AI, DeepSeek, Grok, Poe), most first.
      assistants items(4)
      • assistantstring
        The assistant.
      • sessionsinteger
        Sessions.
      • engaged_sessionsinteger
        Engaged sessions.
      • key_eventsinteger
        Key events.
    • weeklyarray of objects
      AI sessions per week (weeks start on Monday).
      weekly items(3)
      • week_startstring
        Monday of the week, YYYY-MM-DD.
      • totalinteger
        AI sessions that week.
      • by_assistantobject
        Sessions that week per assistant, keyed by assistant name.
    • top_landing_pagesarray of objects
      Pages AI assistants sent visitors to, most first (at most 25).
      top_landing_pages items(4)
      • pagestring
        Landing page path and query string, as GA4 reports it.
      • sessionsinteger
        Sessions.
      • engaged_sessionsinteger
        Engaged sessions.
      • key_eventsinteger
        Key events.

Examples

GET/sites/1/geo/ai-trafficIllustrative

Response · 200 OK
{
  "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
      }
    ]
  }
}

Lists shortened.

Errors

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

API version v1. Every path on this page is relative to https://autoranko.com/api/public/v1.