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
List tracked prompts
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
idintegerRequiredSite ID, from GET /sites.
intentstringOptionalOnly prompts with this intent. An unknown value is rejected with 400 invalid_body.One of
understandingbenefitscomparisonqualityselection- Example
selection
activebooleanOptionaltrue: 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"const res = await fetch("https://autoranko.com/api/public/v1/sites/1/geo/prompts", {
headers: { Authorization: `Bearer ${process.env.AUTORANKO_TOKEN}` },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
for (const p of data.prompts) console.log(p.active ? "on " : "off", p.intent.padEnd(13), p.text);
console.log(`${data.allowance.active_prompts_used}/${data.allowance.active_prompts_limit} active prompts on the account`);import os
import requests
res = requests.get(
"https://autoranko.com/api/public/v1/sites/1/geo/prompts",
headers={"Authorization": f"Bearer {os.environ['AUTORANKO_TOKEN']}"},
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
for p in data["prompts"]:
print("on " if p["active"] else "off", p["intent"].ljust(13), p["text"])
a = data["allowance"]
print(f"{a['active_prompts_used']}/{a['active_prompts_limit']} active prompts on the account")<?php
$ch = curl_init('https://autoranko.com/api/public/v1/sites/1/geo/prompts');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AUTORANKO_TOKEN')],
]);
$data = json_decode(curl_exec($ch), true);
if (isset($data['error'])) throw new RuntimeException($data['error']['message']);
foreach ($data['prompts'] as $p) {
printf("%s %-13s %s\n", $p['active'] ? 'on ' : 'off', $p['intent'], $p['text']);
}Response
200OKThe site's prompts and the account allowance.
application/jsonpromptsarray of objectsPrompts, active first.promptsitems(8)GeoPromptidstringPrompt ID: a 64-bit integer serialized as a string.site_idstringID of the site the prompt is tracked for.textstringThe buyer question, exactly as sent to the models (3 to 300 characters). It never names the brand.intentstringWhat the buyer wants:understanding,benefits,comparison,qualityorselection.One of
understandingbenefitscomparisonqualityselectionsourcestringWhere 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 of
generatedmanualimportapilanguagestringLanguage code of the market it was written for, or an empty string.activebooleantruewhen runs include it. Active prompts count against the account's allowance; inactive ones wait.created_atstring (date-time)When the prompt was added.
allowanceobjectThe account's AI-visibility allowance.allowancekeys(9)GeoAllowanceplanstringThe account's plan.One of
freestarterproscopestringAlwaysaccount: these allowances are shared by all of the account's sites.One of
accountactive_prompts_usedintegerActive prompts across all of the account's sites.active_prompts_limitintegerActive prompts the plan allows (free 5, starter 20, pro 50).manual_runs_usedintegerManual runs started this calendar month (UTC) across the account's sites, from the dashboard and this API.manual_runs_limitintegerManual runs the plan allows per calendar month. Scheduled runs don't count.models_limitintegerModel families (GPT, Claude) a run can track.samples_limitintegerSamples per prompt and model: repeats that measure how stable the answers are.cadencestringHow often scheduled runs happen on this plan.One of
monthlyweekly
Example
Tracked prompts
GET/sites/1/geo/promptsIllustrative
{
"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
| Error | When |
|---|---|
| 400invalid_body | intent isn't one of the five intents (intent must be one of: understanding, benefits, comparison, quality, selection.). |
| 401missing_token | The Authorization: Bearer … header is missing. |
| 401invalid_token | The token is malformed, unknown or revoked, or an OAuth token issued for another resource. |
| 401token_expired | The API key passed its expiry date, or the OAuth access token is more than an hour old. |
| 403insufficient_scope | The API key or OAuth connection doesn't have the geo:read scope. |
| 404not_found | No site with this id belongs to your account (Site not found.). |
| 429rate_limited | The key or OAuth connection made more than 120 requests in the last 60 seconds. |
Add prompts
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
idintegerRequiredSite ID, from GET /sites.
application/jsonpromptsarray of stringsRequiredThe 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?"]
intentstringOptionalOne intent for every prompt in the request. Omit it to label each prompt from its wording.One of
understandingbenefitscomparisonqualityselection- 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?"
]
}'const res = await fetch("https://autoranko.com/api/public/v1/sites/1/geo/prompts", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AUTORANKO_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
prompts: ["How much does a smart irrigation controller save on water bills?", "Is Greenfield Irrigation any good?"],
}),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
for (const p of data.added) console.log("added", p.id, p.text);
for (const r of data.rejected) console.log("skipped", r.text, "-", r.reason);import os
import requests
res = requests.post(
"https://autoranko.com/api/public/v1/sites/1/geo/prompts",
headers={"Authorization": f"Bearer {os.environ['AUTORANKO_TOKEN']}"},
json={
"prompts": ["How much does a smart irrigation controller save on water bills?", "Is Greenfield Irrigation any good?"],
},
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
for p in data["added"]:
print("added", p["id"], p["text"])
for r in data["rejected"]:
print("skipped", r["text"], "-", r["reason"])<?php
$ch = curl_init('https://autoranko.com/api/public/v1/sites/1/geo/prompts');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('AUTORANKO_TOKEN'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'prompts' => ['How much does a smart irrigation controller save on water bills?', 'Is Greenfield Irrigation any good?'],
]),
]);
$data = json_decode(curl_exec($ch), true);
if (isset($data['error'])) throw new RuntimeException($data['error']['message']);
foreach ($data['added'] as $p) echo "added {$p['id']} {$p['text']}\n";
foreach ($data['rejected'] as $r) echo "skipped {$r['text']} - {$r['reason']}\n";Response
201CreatedAt least one prompt was added.
application/jsonaddedarray of objectsThe prompts added (active while the allowance lasted).addeditems(8)GeoPromptidstringPrompt ID: a 64-bit integer serialized as a string.site_idstringID of the site the prompt is tracked for.textstringThe buyer question, exactly as sent to the models (3 to 300 characters). It never names the brand.intentstringWhat the buyer wants:understanding,benefits,comparison,qualityorselection.One of
understandingbenefitscomparisonqualityselectionsourcestringWhere 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 of
generatedmanualimportapilanguagestringLanguage code of the market it was written for, or an empty string.activebooleantruewhen 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 objectsPrompts that weren't added, with why.rejecteditems(2)textstringThe prompt as sent.reasonstringWhy it wasn't added.
allowanceobjectThe allowance after the change.allowancekeys(9)GeoAllowanceplanstringThe account's plan.One of
freestarterproscopestringAlwaysaccount: these allowances are shared by all of the account's sites.One of
accountactive_prompts_usedintegerActive prompts across all of the account's sites.active_prompts_limitintegerActive prompts the plan allows (free 5, starter 20, pro 50).manual_runs_usedintegerManual runs started this calendar month (UTC) across the account's sites, from the dashboard and this API.manual_runs_limitintegerManual runs the plan allows per calendar month. Scheduled runs don't count.models_limitintegerModel families (GPT, Claude) a run can track.samples_limitintegerSamples per prompt and model: repeats that measure how stable the answers are.cadencestringHow often scheduled runs happen on this plan.One of
monthlyweekly
Examples
POST/sites/1/geo/promptsIllustrative
{
"prompts": [
"How much does a smart irrigation controller save on water bills?",
"Is Greenfield Irrigation any good?"
]
}{
"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"
}
}POST/sites/1/geo/promptsIllustrative
{
"prompts": [
"How much does a smart irrigation controller save on water bills?",
"Is Greenfield Irrigation any good?"
]
}{
"error": {
"code": "plan_limit",
"message": "Your plan's AI-visibility prompt allowance is full (20 active prompts across your sites on the starter plan). Archive prompts or upgrade."
}
}Errors
| Error | When |
|---|---|
| 400invalid_body | The body isn't valid JSON (Invalid JSON body.). |
| 400invalid_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).). |
| 400invalid_body | intent isn't one of the five intents (intent must be one of: understanding, benefits, comparison, quality, selection.). |
| 400invalid_body | No prompt could be added (None of the prompts could be added. …, followed by the first reason). |
| 401missing_token | The Authorization: Bearer … header is missing. |
| 401invalid_token | The token is malformed, unknown or revoked, or an OAuth token issued for another resource. |
| 401token_expired | The API key passed its expiry date, or the OAuth access token is more than an hour old. |
| 403insufficient_scope | The API key or OAuth connection doesn't have the geo:write scope. |
| 404not_found | No site with this id belongs to your account (Site not found.). |
| 409idempotency_conflict | The Idempotency-Key was already used for a different request in the last 24 hours. |
| 409idempotency_in_progress | A request with the same Idempotency-Key is still running. |
| 429rate_limited | The key or OAuth connection made more than 120 requests in the last 60 seconds. |
| 429plan_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.). |
Start a run
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.
Request
idintegerRequiredSite ID, from GET /sites.
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"const res = await fetch("https://autoranko.com/api/public/v1/sites/1/geo/runs", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.AUTORANKO_TOKEN}` },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(`Run ${data.run.id}: ${data.run.expected} answers to collect (${data.run.mode})`);import os
import requests
res = requests.post(
"https://autoranko.com/api/public/v1/sites/1/geo/runs",
headers={"Authorization": f"Bearer {os.environ['AUTORANKO_TOKEN']}"},
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(f"Run {data['run']['id']}: {data['run']['expected']} answers to collect ({data['run']['mode']})")<?php
$ch = curl_init('https://autoranko.com/api/public/v1/sites/1/geo/runs');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AUTORANKO_TOKEN')],
CURLOPT_POSTFIELDS => '',
]);
$data = json_decode(curl_exec($ch), true);
if (isset($data['error'])) throw new RuntimeException($data['error']['message']);
echo "Run {$data['run']['id']}: {$data['run']['expected']} answers to collect ({$data['run']['mode']})\n";Response
201CreatedThe run was created in queued.
application/jsonrunobjectThe new run.runkeys(18)GeoRunidstringRun ID: a 64-bit integer serialized as a string.site_idstringID of the site.triggerstringWhat started it: the schedule (cron), the dashboard (manual) or this API (api).One of
cronmanualapimodestringHow the answers behind this number were produced:knowledge(the bare question through the API, no web search) orsearch(the model ran web searches and the provider returned the traces). The two are never mixed.One of
knowledgesearchstatusstringqueuedandrunningwhile answers come in; thendone(every answer received),partial(some failed: seemodel_stats) orfailed(none received).One of
queuedrunningdonepartialfailedmodelsarray of stringsThe tracked models, one per family.samplesintegerTimes each prompt was asked of each model.prompt_countintegerPrompts in the run.expectedintegerAnswers the run asks for:prompt_count× models ×samples.completedintegerAnswers received so far.failedintegerAnswers that failed so far.visibilitynumber or nullShare of received answers that name the brand.nulluntil the run has finished. A number from 0 to 1, ornullwith nothing to count.model_statsarray of objectsPer-model results, once the run has finished (empty before).model_statsitems(9)GeoModelStatmodelstringThe tracked model, such asgpt-6-astraorclaude-sonnet-5-5. Answers are attributed to the model asked, never to a fallback.providerstring or nullWhich service answered for it, ornullif none did.One of
kieopenaianthropicdataforseomodestringHow the answers behind this number were produced:knowledge(the bare question through the API, no web search) orsearch(the model ran web searches and the provider returned the traces). The two are never mixed.One of
knowledgesearchcompletedintegerAnswers received.failedintegerAnswers that failed (the model or its relay was unavailable, timed out, or returned nothing).mentionedintegerReceived answers that name the brand, an alias or one of its domains.visibilitynumber or nullmentioned/completed. A number from 0 to 1, ornullwith nothing to count.avg_mention_ranknumber or nullAverage position of the brand among the names an answer lists (1 = named first), over the answers that name it;nullwhen none does.last_errorstring or nullThe last failure for this model in the run, ornull.
notesstring or nullWhy the run differs from the settings (for example, live search requested but unavailable), ornull.errorstring or nullWhy afailedrun failed, ornull.created_atstring (date-time)When the run was started.started_atstring (date-time) or nullWhen the first answer was requested, ornull.finished_atstring (date-time) or nullWhen the run finished, ornullwhile it's open.
Examples
POST/sites/1/geo/runsIllustrative
{
"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
}
}POST/sites/1/geo/runsIllustrative
{
"error": {
"code": "invalid_state",
"message": "An AI-visibility run is already in progress for this site."
}
}POST/sites/1/geo/runsIllustrative
{
"error": {
"code": "plan_limit",
"message": "Manual AI-visibility runs used up for this month (1 on the free plan). Scheduled runs continue."
}
}Errors
| Error | When |
|---|---|
| 401missing_token | The Authorization: Bearer … header is missing. |
| 401invalid_token | The token is malformed, unknown or revoked, or an OAuth token issued for another resource. |
| 401token_expired | The API key passed its expiry date, or the OAuth access token is more than an hour old. |
| 403insufficient_scope | The API key or OAuth connection doesn't have the geo:write scope. |
| 404not_found | No site with this id belongs to your account (Site not found.). |
| 409invalid_state | A run is already queued or running for the site (An AI-visibility run is already in progress for this site.). |
| 409invalid_state | The site has no active prompt (Add prompts before starting a run.). |
| 409idempotency_conflict | The Idempotency-Key was already used for a different request in the last 24 hours. |
| 409idempotency_in_progress | A request with the same Idempotency-Key is still running. |
| 429rate_limited | The key or OAuth connection made more than 120 requests in the last 60 seconds. |
| 429plan_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.). |
List runs
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
idintegerRequiredSite ID, from GET /sites.
limitintegerOptionalHow 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"const res = await fetch("https://autoranko.com/api/public/v1/sites/1/geo/runs?limit=10", {
headers: { Authorization: `Bearer ${process.env.AUTORANKO_TOKEN}` },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
for (const r of data.runs) console.log(r.id, r.status, r.mode, r.visibility ?? `${r.completed}/${r.expected}`);import os
import requests
res = requests.get(
"https://autoranko.com/api/public/v1/sites/1/geo/runs",
headers={"Authorization": f"Bearer {os.environ['AUTORANKO_TOKEN']}"},
params={"limit": 10},
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
for r in data["runs"]:
print(r["id"], r["status"], r["mode"], r["visibility"])<?php
$ch = curl_init('https://autoranko.com/api/public/v1/sites/1/geo/runs?limit=10');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AUTORANKO_TOKEN')],
]);
$data = json_decode(curl_exec($ch), true);
if (isset($data['error'])) throw new RuntimeException($data['error']['message']);
foreach ($data['runs'] as $r) echo "{$r['id']} {$r['status']} {$r['mode']}\n";Response
200OKThe newest runs.
application/jsonrunsarray of objectsRuns, newest first.runsitems(18)GeoRunidstringRun ID: a 64-bit integer serialized as a string.site_idstringID of the site.triggerstringWhat started it: the schedule (cron), the dashboard (manual) or this API (api).One of
cronmanualapimodestringHow the answers behind this number were produced:knowledge(the bare question through the API, no web search) orsearch(the model ran web searches and the provider returned the traces). The two are never mixed.One of
knowledgesearchstatusstringqueuedandrunningwhile answers come in; thendone(every answer received),partial(some failed: seemodel_stats) orfailed(none received).One of
queuedrunningdonepartialfailedmodelsarray of stringsThe tracked models, one per family.samplesintegerTimes each prompt was asked of each model.prompt_countintegerPrompts in the run.expectedintegerAnswers the run asks for:prompt_count× models ×samples.completedintegerAnswers received so far.failedintegerAnswers that failed so far.visibilitynumber or nullShare of received answers that name the brand.nulluntil the run has finished. A number from 0 to 1, ornullwith nothing to count.model_statsarray of objectsPer-model results, once the run has finished (empty before).model_statsitems(9)GeoModelStatmodelstringThe tracked model, such asgpt-6-astraorclaude-sonnet-5-5. Answers are attributed to the model asked, never to a fallback.providerstring or nullWhich service answered for it, ornullif none did.One of
kieopenaianthropicdataforseomodestringHow the answers behind this number were produced:knowledge(the bare question through the API, no web search) orsearch(the model ran web searches and the provider returned the traces). The two are never mixed.One of
knowledgesearchcompletedintegerAnswers received.failedintegerAnswers that failed (the model or its relay was unavailable, timed out, or returned nothing).mentionedintegerReceived answers that name the brand, an alias or one of its domains.visibilitynumber or nullmentioned/completed. A number from 0 to 1, ornullwith nothing to count.avg_mention_ranknumber or nullAverage position of the brand among the names an answer lists (1 = named first), over the answers that name it;nullwhen none does.last_errorstring or nullThe last failure for this model in the run, ornull.
notesstring or nullWhy the run differs from the settings (for example, live search requested but unavailable), ornull.errorstring or nullWhy afailedrun failed, ornull.created_atstring (date-time)When the run was started.started_atstring (date-time) or nullWhen the first answer was requested, ornull.finished_atstring (date-time) or nullWhen the run finished, ornullwhile it's open.
Example
Recent runs
GET/sites/1/geo/runs?limit=1Illustrative
{
"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
| Error | When |
|---|---|
| 401missing_token | The Authorization: Bearer … header is missing. |
| 401invalid_token | The token is malformed, unknown or revoked, or an OAuth token issued for another resource. |
| 401token_expired | The API key passed its expiry date, or the OAuth access token is more than an hour old. |
| 403insufficient_scope | The API key or OAuth connection doesn't have the geo:read scope. |
| 404not_found | No site with this id belongs to your account (Site not found.). |
| 429rate_limited | The key or OAuth connection made more than 120 requests in the last 60 seconds. |
Get a run with its answers
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
idintegerRequiredRun ID, from POST /sites/{id}/geo/runs or GET /sites/{id}/geo/runs.
limitintegerOptionalAnswers per page. Values outside 1–500 are clamped.- Default
100- Range
1–500- Example
100
offsetintegerOptionalAnswers to skip, for pagination.- Default
0- Minimum
0- Example
0
modelstringOptionalOnly this model's answers, such asgpt-6-astra.- Example
gpt-6-astra
statusstringOptionalOnly answers in this status. An unknown value is rejected with 400 invalid_body.One of
pendingrunningokfailed- Example
ok
curl "https://autoranko.com/api/public/v1/geo/runs/12?status=ok&limit=100" \
-H "Authorization: Bearer $AUTORANKO_TOKEN"const res = await fetch("https://autoranko.com/api/public/v1/geo/runs/12?status=ok&limit=100", {
headers: { Authorization: `Bearer ${process.env.AUTORANKO_TOKEN}` },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
const { run, answers } = data;
console.log(`${run.status} (${run.mode}): ${run.completed}/${run.expected} answers`);
for (const a of answers) console.log(a.model, a.mentioned ? `named #${a.mention_rank ?? "?"}` : "not named", a.prompt_text);import os
import requests
res = requests.get(
"https://autoranko.com/api/public/v1/geo/runs/12",
headers={"Authorization": f"Bearer {os.environ['AUTORANKO_TOKEN']}"},
params={"status": "ok", "limit": 100},
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
run = data["run"]
print(f"{run['status']} ({run['mode']}): {run['completed']}/{run['expected']} answers")
for a in data["answers"]:
print(a["model"], "named" if a["mentioned"] else "not named", a["prompt_text"])<?php
$ch = curl_init('https://autoranko.com/api/public/v1/geo/runs/12?status=ok&limit=100');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AUTORANKO_TOKEN')],
]);
$data = json_decode(curl_exec($ch), true);
if (isset($data['error'])) throw new RuntimeException($data['error']['message']);
foreach ($data['answers'] as $a) {
echo $a['model'], ' ', $a['mentioned'] ? 'named' : 'not named', ' ', $a['prompt_text'], "\n";
}Response
200OKThe run and one page of its answers.
application/jsonrunobjectThe run.runkeys(18)GeoRunidstringRun ID: a 64-bit integer serialized as a string.site_idstringID of the site.triggerstringWhat started it: the schedule (cron), the dashboard (manual) or this API (api).One of
cronmanualapimodestringHow the answers behind this number were produced:knowledge(the bare question through the API, no web search) orsearch(the model ran web searches and the provider returned the traces). The two are never mixed.One of
knowledgesearchstatusstringqueuedandrunningwhile answers come in; thendone(every answer received),partial(some failed: seemodel_stats) orfailed(none received).One of
queuedrunningdonepartialfailedmodelsarray of stringsThe tracked models, one per family.samplesintegerTimes each prompt was asked of each model.prompt_countintegerPrompts in the run.expectedintegerAnswers the run asks for:prompt_count× models ×samples.completedintegerAnswers received so far.failedintegerAnswers that failed so far.visibilitynumber or nullShare of received answers that name the brand.nulluntil the run has finished. A number from 0 to 1, ornullwith nothing to count.model_statsarray of objectsPer-model results, once the run has finished (empty before).model_statsitems(9)GeoModelStatmodelstringThe tracked model, such asgpt-6-astraorclaude-sonnet-5-5. Answers are attributed to the model asked, never to a fallback.providerstring or nullWhich service answered for it, ornullif none did.One of
kieopenaianthropicdataforseomodestringHow the answers behind this number were produced:knowledge(the bare question through the API, no web search) orsearch(the model ran web searches and the provider returned the traces). The two are never mixed.One of
knowledgesearchcompletedintegerAnswers received.failedintegerAnswers that failed (the model or its relay was unavailable, timed out, or returned nothing).mentionedintegerReceived answers that name the brand, an alias or one of its domains.visibilitynumber or nullmentioned/completed. A number from 0 to 1, ornullwith nothing to count.avg_mention_ranknumber or nullAverage position of the brand among the names an answer lists (1 = named first), over the answers that name it;nullwhen none does.last_errorstring or nullThe last failure for this model in the run, ornull.
notesstring or nullWhy the run differs from the settings (for example, live search requested but unavailable), ornull.errorstring or nullWhy afailedrun failed, ornull.created_atstring (date-time)When the run was started.started_atstring (date-time) or nullWhen the first answer was requested, ornull.finished_atstring (date-time) or nullWhen the run finished, ornullwhile it's open.
answersarray of objectsOne page of answers.answersitems(23)GeoAnsweridstringAnswer ID: a 64-bit integer serialized as a string.run_idstringID of the run.prompt_idstring or nullID of the prompt, ornullif the prompt was deleted.prompt_textstringThe exact text that was sent, as it was when the run started.intentstringThe prompt's intent at the time.One of
understandingbenefitscomparisonqualityselectionmodelstringThe model asked. The answer is attributed to it and nothing else.model_servedstring or nullThe model the provider reported it ran, ornullbefore an answer.providerstringThe service that answered.One of
kieopenaianthropicdataforseomodestringHow the answers behind this number were produced:knowledge(the bare question through the API, no web search) orsearch(the model ran web searches and the provider returned the traces). The two are never mixed.One of
knowledgesearchsampleintegerWhich repeat of this prompt and model (1 to the run'ssamples).statusstringpendingandrunninguntil answered, thenokorfailed.One of
pendingrunningokfailedanswerstring or nullThe full answer text, ornulluntil there is one.errorstring or nullWhy the answer failed, ornull.mentionedboolean or nullWhether the answer names the brand, an alias or one of its domains (exact match).nullunlessstatusisok.mention_rankinteger or nullPosition of the brand among the names the answer lists, ornullwhen it isn't named or the order couldn't be read.domain_mentionedboolean or nullWhether one of the site's domains appears in the answer.nullunlessstatusisok.entitiesarray of objectsEvery company, brand or product the answer names, in order (read by a separate extraction call).entitiesitems(4)GeoEntitynamestringA company, brand or product the answer names, as written (your brand under its brand name).domainstring or nullIts domain when the answer writes one, elsenull.rankintegerOrder of first appearance in the answer (1 = first).brandbooleantruefor your brand (matched exactly on its name, aliases or domains).
urls_writtenarray of objectsURLs written in the answer text. Inknowledgemode these are URLs the model wrote from memory: unverified, never sources.urls_writtenitems(3)GeoLinkurlstring (uri)The URL.domainstringIts registrable domain, such asexample.co.uk.titlestringOptionalThe page title the provider returned (citations only).
searchesarray of stringsSearch queries: observed in the provider's traces (searches_kind: observed) or what the model said it would search when asked separately (predicted).searches_kindstringobserved(tool traces),predicted(asked separately; not observed) ornone.One of
observedpredictednonecitationsarray of objectsSources the provider returned with asearchanswer. Always empty inknowledgemode.citationsitems(3)GeoLinkurlstring (uri)The URL.domainstringIts registrable domain, such asexample.co.uk.titlestringOptionalThe page title the provider returned (citations only).
created_atstring (date-time)When the answer was queued.answered_atstring (date-time) or nullWhen it was answered or failed, ornull.
limitintegerThe page size applied.offsetintegerThe offset applied.
Examples
GET/geo/runs/12?limit=2Illustrative
{
"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.
GET/geo/runs/9999Illustrative
{
"error": {
"code": "not_found",
"message": "Run not found."
}
}Errors
| Error | When |
|---|---|
| 400invalid_body | status isn't an answer status (status must be one of: pending, running, ok, failed.). |
| 401missing_token | The Authorization: Bearer … header is missing. |
| 401invalid_token | The token is malformed, unknown or revoked, or an OAuth token issued for another resource. |
| 401token_expired | The API key passed its expiry date, or the OAuth access token is more than an hour old. |
| 403insufficient_scope | The API key or OAuth connection doesn't have the geo:read scope. |
| 404not_found | No run with this id belongs to your account (Run not found.). |
| 429rate_limited | The key or OAuth connection made more than 120 requests in the last 60 seconds. |
Get visibility metrics
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.
null when there's nothing to count, such as stability with one sample.Request
idintegerRequiredSite ID, from GET /sites.
modestringOptionalThe mode to report. Without it: the mode of the latest finished run. An unknown value is rejected with 400 invalid_body.One of
knowledgesearch- Example
knowledge
curl "https://autoranko.com/api/public/v1/sites/1/geo/stats?mode=knowledge" \
-H "Authorization: Bearer $AUTORANKO_TOKEN"const res = await fetch("https://autoranko.com/api/public/v1/sites/1/geo/stats?mode=knowledge", {
headers: { Authorization: `Bearer ${process.env.AUTORANKO_TOKEN}` },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
const { stats } = data;
console.log(stats.disclaimer);
for (const m of stats.by_model) console.log(m.model, `${Math.round((m.visibility ?? 0) * 100)}% of answers name us`);import os
import requests
res = requests.get(
"https://autoranko.com/api/public/v1/sites/1/geo/stats",
headers={"Authorization": f"Bearer {os.environ['AUTORANKO_TOKEN']}"},
params={"mode": "knowledge"},
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
stats = data["stats"]
print(stats["disclaimer"])
for m in stats["by_model"]:
print(m["model"], f"{round((m['visibility'] or 0) * 100)}% of answers name us")<?php
$ch = curl_init('https://autoranko.com/api/public/v1/sites/1/geo/stats?mode=knowledge');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AUTORANKO_TOKEN')],
]);
$data = json_decode(curl_exec($ch), true);
if (isset($data['error'])) throw new RuntimeException($data['error']['message']);
$stats = $data['stats'];
echo $stats['disclaimer'], "\n";
foreach ($stats['by_model'] as $m) printf("%s %d%%\n", $m['model'], round(($m['visibility'] ?? 0) * 100));Response
200OKThe metrics.
application/jsonstatsobjectAI-visibility metrics.statskeys(14)GeoStatssite_idstringID of the site.modestringHow the answers behind this number were produced:knowledge(the bare question through the API, no web search) orsearch(the model ran web searches and the provider returned the traces). The two are never mixed.One of
knowledgesearchdisclaimerstringThe label that goes with every number of this mode, naming the tracked models. Show it next to them.modes_availablearray of stringsModes with at least one finished run.One of
knowledgesearchrunobject or nullThe latest finished run of this mode, which the metrics below describe, ornullbefore the first one.runkeys(18)GeoRunidstringRun ID: a 64-bit integer serialized as a string.site_idstringID of the site.triggerstringWhat started it: the schedule (cron), the dashboard (manual) or this API (api).One of
cronmanualapimodestringHow the answers behind this number were produced:knowledge(the bare question through the API, no web search) orsearch(the model ran web searches and the provider returned the traces). The two are never mixed.One of
knowledgesearchstatusstringqueuedandrunningwhile answers come in; thendone(every answer received),partial(some failed: seemodel_stats) orfailed(none received).One of
queuedrunningdonepartialfailedmodelsarray of stringsThe tracked models, one per family.samplesintegerTimes each prompt was asked of each model.prompt_countintegerPrompts in the run.expectedintegerAnswers the run asks for:prompt_count× models ×samples.completedintegerAnswers received so far.failedintegerAnswers that failed so far.visibilitynumber or nullShare of received answers that name the brand.nulluntil the run has finished. A number from 0 to 1, ornullwith nothing to count.model_statsarray of objectsPer-model results, once the run has finished (empty before).model_statsitems(9)GeoModelStatmodelstringThe tracked model, such asgpt-6-astraorclaude-sonnet-5-5. Answers are attributed to the model asked, never to a fallback.providerstring or nullWhich service answered for it, ornullif none did.One of
kieopenaianthropicdataforseomodestringHow the answers behind this number were produced:knowledge(the bare question through the API, no web search) orsearch(the model ran web searches and the provider returned the traces). The two are never mixed.One of
knowledgesearchcompletedintegerAnswers received.failedintegerAnswers that failed (the model or its relay was unavailable, timed out, or returned nothing).mentionedintegerReceived answers that name the brand, an alias or one of its domains.visibilitynumber or nullmentioned/completed. A number from 0 to 1, ornullwith nothing to count.avg_mention_ranknumber or nullAverage position of the brand among the names an answer lists (1 = named first), over the answers that name it;nullwhen none does.last_errorstring or nullThe last failure for this model in the run, ornull.
notesstring or nullWhy the run differs from the settings (for example, live search requested but unavailable), ornull.errorstring or nullWhy afailedrun failed, ornull.created_atstring (date-time)When the run was started.started_atstring (date-time) or nullWhen the first answer was requested, ornull.finished_atstring (date-time) or nullWhen the run finished, ornullwhile it's open.
visibilitynumber or nullShare of the run's answers that name the brand. A number from 0 to 1, ornullwith nothing to count.avg_mention_ranknumber or nullAverage position of the brand where it is named, ornull.share_of_voicenumber or nullBrand mentions / all name mentions in the run's answers (each answer counts each name once). A number from 0 to 1, ornullwith nothing to count.stabilitynumber or nullShare of prompt × model pairs whose samples agree (all name the brand, or none).nullwith one sample. A number from 0 to 1, ornullwith nothing to count.samplesintegerSamples per prompt and model in the run.by_modelarray of objectsThe same metrics per tracked model.by_modelitems(8)modelstringThe model.modestringHow the answers behind this number were produced:knowledge(the bare question through the API, no web search) orsearch(the model ran web searches and the provider returned the traces). The two are never mixed.One of
knowledgesearchcompletedintegerAnswers received.mentionedintegerAnswers that name the brand.visibilitynumber or nullmentioned/completed. A number from 0 to 1, ornullwith nothing to count.avg_mention_ranknumber or nullAverage position where named, ornull.share_of_voicenumber or nullShare of voice in this model's answers. A number from 0 to 1, ornullwith nothing to count.stabilitynumber or nullStability of this model's answers. A number from 0 to 1, ornullwith nothing to count.
by_intentarray of objectsVisibility per prompt intent.by_intentitems(5)intentstringThe intent.One of
understandingbenefitscomparisonqualityselectionmodestringHow the answers behind this number were produced:knowledge(the bare question through the API, no web search) orsearch(the model ran web searches and the provider returned the traces). The two are never mixed.One of
knowledgesearchcompletedintegerAnswers received.mentionedintegerAnswers that name the brand.visibilitynumber or nullmentioned/completed. A number from 0 to 1, ornullwith nothing to count.
by_promptarray of objectsVisibility per prompt, least visible first: the prompts to write content for.by_promptitems(8)prompt_idstring or nullID of the prompt, ornull.textstringThe prompt as sent.intentstringIts intent.One of
understandingbenefitscomparisonqualityselectionmodestringHow the answers behind this number were produced:knowledge(the bare question through the API, no web search) orsearch(the model ran web searches and the provider returned the traces). The two are never mixed.One of
knowledgesearchcompletedintegerAnswers received.mentionedintegerAnswers that name the brand.visibilitynumber or nullmentioned/completed. A number from 0 to 1, ornullwith nothing to count.by_modelarray of objectsPer model.by_modelitems(4)modelstringThe model.completedintegerAnswers received.mentionedintegerAnswers that name the brand.visibilitynumber or nullmentioned/completed. A number from 0 to 1, ornullwith nothing to count.
trendarray of objectsFinished runs of the same mode, oldest first (at most 26). Knowledge and search runs never share a trend.trenditems(5)run_idstringID of the run.finished_atstring (date-time) or nullWhen it finished.modestringHow the answers behind this number were produced:knowledge(the bare question through the API, no web search) orsearch(the model ran web searches and the provider returned the traces). The two are never mixed.One of
knowledgesearchvisibilitynumber or nullThe run's visibility. A number from 0 to 1, ornullwith nothing to count.by_modelarray of objectsPer model.by_modelitems(2)modelstringThe model.visibilitynumber or nullThe model's visibility in that run. A number from 0 to 1, ornullwith nothing to count.
Example
Model-knowledge metrics
GET/sites/1/geo/statsIllustrative
{
"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
| Error | When |
|---|---|
| 400invalid_body | mode isn't knowledge or search (mode must be one of: knowledge, search.). |
| 401missing_token | The Authorization: Bearer … header is missing. |
| 401invalid_token | The token is malformed, unknown or revoked, or an OAuth token issued for another resource. |
| 401token_expired | The API key passed its expiry date, or the OAuth access token is more than an hour old. |
| 403insufficient_scope | The API key or OAuth connection doesn't have the geo:read scope. |
| 404not_found | No site with this id belongs to your account (Site not found.). |
| 429rate_limited | The key or OAuth connection made more than 120 requests in the last 60 seconds. |
List the names AI answers give
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
idintegerRequiredSite ID, from GET /sites.
modestringOptionalThe mode to report. Without it: the mode of the latest finished run.One of
knowledgesearch- Example
knowledge
limitintegerOptionalHow 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"const res = await fetch("https://autoranko.com/api/public/v1/sites/1/geo/competitors?limit=10", {
headers: { Authorization: `Bearer ${process.env.AUTORANKO_TOKEN}` },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
for (const c of data.competitors) console.log(c.brand ? "(you)" : " ", c.name, c.answers, `avg #${c.avg_rank}`);import os
import requests
res = requests.get(
"https://autoranko.com/api/public/v1/sites/1/geo/competitors",
headers={"Authorization": f"Bearer {os.environ['AUTORANKO_TOKEN']}"},
params={"limit": 10},
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
for c in data["competitors"]:
print("(you)" if c["brand"] else " ", c["name"], c["answers"])<?php
$ch = curl_init('https://autoranko.com/api/public/v1/sites/1/geo/competitors?limit=10');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AUTORANKO_TOKEN')],
]);
$data = json_decode(curl_exec($ch), true);
if (isset($data['error'])) throw new RuntimeException($data['error']['message']);
foreach ($data['competitors'] as $c) echo ($c['brand'] ? '(you) ' : ''), $c['name'], ' ', $c['answers'], "\n";Response
200OKThe leaderboard.
application/jsonsite_idstringID of the site.modestringHow the answers behind this number were produced:knowledge(the bare question through the API, no web search) orsearch(the model ran web searches and the provider returned the traces). The two are never mixed.One of
knowledgesearchdisclaimerstringThe label for these numbers.run_idstring or nullThe run they come from, ornullbefore the first finished run.answers_consideredintegerAnswers read.competitorsarray of objectsNames, most named first.competitorsitems(9)GeoCompetitornamestringThe name as answers write it (after your merge rules).domainstring or nullIts domain when an answer wrote one, elsenull.brandbooleantruefor your own brand.modestringHow the answers behind this number were produced:knowledge(the bare question through the API, no web search) orsearch(the model ran web searches and the provider returned the traces). The two are never mixed.One of
knowledgesearchanswersintegerAnswers that name it.answer_sharenumber or nullanswers/ answers considered. A number from 0 to 1, ornullwith nothing to count.share_of_voicenumber or nullIts mentions / all name mentions. A number from 0 to 1, ornullwith nothing to count.avg_ranknumber or nullAverage position where it is named.modelsarray of stringsModels whose answers name it.
hiddenarray of stringsNames you hid (lowercase).
Example
Leaderboard
GET/sites/1/geo/competitors?limit=3Illustrative
{
"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
| Error | When |
|---|---|
| 400invalid_body | mode isn't knowledge or search (mode must be one of: knowledge, search.). |
| 401missing_token | The Authorization: Bearer … header is missing. |
| 401invalid_token | The token is malformed, unknown or revoked, or an OAuth token issued for another resource. |
| 401token_expired | The API key passed its expiry date, or the OAuth access token is more than an hour old. |
| 403insufficient_scope | The API key or OAuth connection doesn't have the geo:read scope. |
| 404not_found | No site with this id belongs to your account (Site not found.). |
| 429rate_limited | The key or OAuth connection made more than 120 requests in the last 60 seconds. |
Get AI-assistant traffic (GA4)
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
idintegerRequiredSite ID, from GET /sites.
daysintegerOptionalFull 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"const res = await fetch("https://autoranko.com/api/public/v1/sites/1/geo/ai-traffic?days=28", {
headers: { Authorization: `Bearer ${process.env.AUTORANKO_TOKEN}` },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
const { traffic } = data;
console.log(`${traffic.totals.ai_sessions} AI sessions (${((traffic.totals.ai_share ?? 0) * 100).toFixed(1)}% of all)`);
for (const a of traffic.assistants) console.log(a.assistant, a.sessions);import os
import requests
res = requests.get(
"https://autoranko.com/api/public/v1/sites/1/geo/ai-traffic",
headers={"Authorization": f"Bearer {os.environ['AUTORANKO_TOKEN']}"},
params={"days": 28},
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
t = data["traffic"]
print(t["totals"]["ai_sessions"], "AI sessions")
for a in t["assistants"]:
print(a["assistant"], a["sessions"])<?php
$ch = curl_init('https://autoranko.com/api/public/v1/sites/1/geo/ai-traffic?days=28');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AUTORANKO_TOKEN')],
]);
$data = json_decode(curl_exec($ch), true);
if (isset($data['error'])) throw new RuntimeException($data['error']['message']);
$t = $data['traffic'];
foreach ($t['assistants'] as $a) echo "{$a['assistant']} {$a['sessions']}\n";Response
200OKThe report.
application/jsontrafficobjectAI-assistant sessions.traffickeys(9)GeoTrafficsite_idstringID of the site.propertystringThe GA4 property the numbers come from (properties/…).daysintegerFull days covered, ending yesterday in the property's time zone (7 to 90).notestringAlways: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).totalsobjectTotals over the period.totalskeys(5)ai_sessionsintegerSessions whose source is an AI assistant.ai_engaged_sessionsintegerEngaged sessions among them (GA4's definition).ai_key_eventsintegerKey events in those sessions.all_sessionsintegerAll sessions of the property, for comparison.ai_sharenumber or nullai_sessions/all_sessions. A number from 0 to 1, ornullwith nothing to count.
assistantsarray of objectsSessions per assistant (ChatGPT, Perplexity, Claude, Gemini, Copilot, You.com, Meta AI, DeepSeek, Grok, Poe), most first.assistantsitems(4)assistantstringThe assistant.sessionsintegerSessions.engaged_sessionsintegerEngaged sessions.key_eventsintegerKey events.
weeklyarray of objectsAI sessions per week (weeks start on Monday).weeklyitems(3)week_startstringMonday of the week,YYYY-MM-DD.totalintegerAI sessions that week.by_assistantobjectSessions that week per assistant, keyed by assistant name.
top_landing_pagesarray of objectsPages AI assistants sent visitors to, most first (at most 25).top_landing_pagesitems(4)pagestringLanding page path and query string, as GA4 reports it.sessionsintegerSessions.engaged_sessionsintegerEngaged sessions.key_eventsintegerKey events.
Examples
GET/sites/1/geo/ai-trafficIllustrative
{
"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.
GET/sites/1/geo/ai-trafficIllustrative
{
"error": {
"code": "invalid_state",
"message": "Connect Google Analytics in Dashboard → AI Visibility first."
}
}Errors
| Error | When |
|---|---|
| 401missing_token | The Authorization: Bearer … header is missing. |
| 401invalid_token | The token is malformed, unknown or revoked, or an OAuth token issued for another resource. |
| 401token_expired | The API key passed its expiry date, or the OAuth access token is more than an hour old. |
| 403insufficient_scope | The API key or OAuth connection doesn't have the geo:read scope. |
| 404not_found | No site with this id belongs to your account (Site not found.). |
| 409invalid_state | Google sign-in isn't configured on the server (Google sign-in isn't configured on this server yet.). |
| 409invalid_state | Google Analytics isn't connected, or access was revoked (Connect Google Analytics in Dashboard → AI Visibility first.). |
| 409invalid_state | No GA4 property is chosen for the site (Choose a GA4 property in Dashboard → AI Visibility → AI traffic first.). |
| 429rate_limited | The key or OAuth connection made more than 120 requests in the last 60 seconds. |
| 502upstream_error | Google 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.