AI visibility API
Ask AI answer engines a question and see whether a brand is mentioned and cited, at what position, next to which competitors, and which URLs they cite.
How it works
POST /v1/checkwith a question, a brand and the engines to ask. The price is taken from your balance up front and you get a check id (202).- Poll
GET /v1/checks/{id}until it finishes. Each engine answerssamplestimes; failed answers are refunded automatically. - Read the rates per engine. Every rate comes with its sample count, and the mention rate with a Wilson 95% interval.
Base URL https://api.sagbot.app, token as Authorization: Bearer sgb_… (get a token). GET /v1/engines and GET /v1/health need no token.
Engines and prices
You pay per answer: one engine, one sample. A check costs the sum of price × samples over its engines. Without engines, a check asks the five default engines: chatgpt, google_aio, gemini, google_ai_mode and perplexity.
| Engine id | Label | Surface | Per answer |
|---|---|---|---|
chatgpt | ChatGPT | ui | $0.035 |
google_aio | Google AI Overviews | ui | $0.035 |
gemini | Gemini | ui | $0.035 |
google_ai_mode | Google AI Mode | ui | $0.035 |
perplexity | Perplexity | api | $0.035 |
claude | Claude | api | $0.06 |
chatgpt_api | ChatGPT (API) | api | $0.06 |
gemini_api | Gemini (API) | api | $0.06 |
ui: the answer a logged-out user sees in the product. api: the model through its API, with web search on.
GET /v1/enginesno token
The live catalog, sorted by share of AI referral traffic: id, label, surface (ui: what a logged-out user sees in the product; api: the model through its API with web search on), vendor, price_usd, traffic_rank, default, status (ok, degraded or off) and supports (country, language, citations, fan-out, sponsored).
curl https://api.sagbot.app/v1/enginesCreate a check
POST /v1/check202, or 200 for a dry run
| Field | Type | Description |
|---|---|---|
query | string, required | The question, 1 to 300 characters |
brand.name | string, required | 1 to 100 characters |
brand.domain | string | A host such as sagbot.app; citations on it or its subdomains count as cited |
brand.aliases | string[] | Other names of the brand, up to 10 |
competitors | string[] | Up to 10 names, each reported with its own rates |
engines | string[] | Distinct engine ids. Default: the five default engines |
country | string | ISO 3166-1 alpha-2, default US. The list is in openapi.yaml |
language | string | ISO 639-1, optionally with a region (en, pt-BR). Default en |
samples | integer | 1 to 5, default 1. More samples give a mention rate with a narrower interval |
include | string[] | ["raw"] adds each answer's text to the result |
dry_run | boolean | true returns the price and charges nothing |
Send an Idempotency-Key header (1 to 64 characters, your own id for this check) to retry safely: a repeat with the same key returns the same check, id and cost, and is never charged twice. After a 402, top up and use a new key.
curl https://api.sagbot.app/v1/check \
-H "Authorization: Bearer $SAGBOT_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: weekly-2026-11-17-sagbot" \
-d '{
"query": "best tool to check if my website is ready for ai agents",
"brand": { "name": "SagBot", "domain": "sagbot.app" },
"competitors": ["Acme Audit"],
"engines": ["chatgpt", "perplexity"],
"samples": 3
}'202: charged and queued. X-Cost-USD and X-Balance-USD show the price and your balance after paying.
{ "id": "chk_0f8e6c1d2b3a49e8a7c6b5d4e3f2a1b0", "status": "queued", "cost_usd": 0.21 }With "dry_run": true: 200 and the price, line by line.
{
"cost_usd": 0.21,
"lines": [
{ "engine": "chatgpt", "samples": 3, "unit_usd": 0.035, "usd": 0.105 },
{ "engine": "perplexity", "samples": 3, "unit_usd": 0.035, "usd": 0.105 }
]
}Get a check
GET /v1/checks/{id}
Poll until status is done, partial (some answers failed and were refunded) or failed; before that it is queued or running and results is null. Only the token's owner can read a check; anyone else gets 404.
curl https://api.sagbot.app/v1/checks/chk_0f8e6c1d2b3a49e8a7c6b5d4e3f2a1b0 \
-H "Authorization: Bearer $SAGBOT_TOKEN"{
"id": "chk_0f8e6c1d2b3a49e8a7c6b5d4e3f2a1b0",
"status": "done",
"created_at": "2026-11-17T09:41:07.000Z",
"finished_at": "2026-11-17T09:42:31.000Z",
"cost_usd": 0.21,
"refunded_usd": 0,
"request": {
"query": "best tool to check if my website is ready for ai agents",
"brand": { "name": "SagBot", "domain": "sagbot.app", "aliases": [] },
"competitors": ["Acme Audit"],
"engines": ["chatgpt", "perplexity"],
"country": "US",
"language": "en",
"samples": 3,
"include": []
},
"results": [
{
"engine": "chatgpt",
"surface": "ui",
"model": "chatgpt",
"samples": 3,
"samples_ok": 3,
"mentioned_rate": 0.67,
"ci95": [0.21, 0.94],
"cited_rate": 0.33,
"avg_position": 1.5,
"surface_present_rate": 1,
"web_search_rate": null,
"sample_flags": [
{ "sample": 1, "no_web_search": false, "no_citations": false },
{ "sample": 2, "no_web_search": false, "no_citations": false },
{ "sample": 3, "no_web_search": false, "no_citations": true }
],
"fan_out": ["ai agent readiness checker website"],
"competitors": [{ "name": "Acme Audit", "mentioned_rate": 0.33, "avg_position": 2 }],
"citations": [
{ "url": "https://sagbot.app/", "title": "SagBot", "domain": "sagbot.app", "count": 1, "brand": true }
],
"errors": []
}
]
}Result fields
One entry per engine in results. Rates are over the answers that succeeded (samples_ok), and null when none did.
| Field | Description |
|---|---|
surface | ui or api, as in the engine catalog |
model | The model the supplier reported (or the engine id); null only when no answer succeeded |
samples, samples_ok | Answers asked for, and answers that came back |
mentioned_rate | Share of answers that mention the brand (or an alias) |
ci95 | Wilson 95% interval of mentioned_rate |
cited_rate | Share of answers citing brand.domain |
avg_position | Mean rank of the brand's first mention among brand and competitors; 1 = first |
surface_present_rate | Share of answers where the surface appeared at all (Google shows no AI Overview for many queries) |
web_search_rate | Share of answers where the model searched the web; null when the supplier doesn't say (UI engines) |
sample_flags | Per answer: no_web_search and no_citations, so "not cited" is never read as "didn't search" |
fan_out | The web searches the engine ran to answer; empty when it doesn't report them |
competitors | name, mentioned_rate, avg_position per competitor |
citations | Cited URLs, most cited first: url, title, domain, count (answers citing it), brand (on brand.domain) |
errors | Failed answers: sample and code (timeout or upstream_error); each was refunded |
raw | Only with include: ["raw"]: each answer's text, null for failed ones |
Usage
GET /v1/usage?days=30
What you spent on AI visibility per day and engine; refunded answers are not counted. days is 1 to 90, default 30.
curl "https://api.sagbot.app/v1/usage?days=30" -H "Authorization: Bearer $SAGBOT_TOKEN"
{
"days": 30,
"total_usd": 0.21,
"rows": [
{ "day": "2026-11-17", "engine": "chatgpt", "samples": 3, "usd": 0.105 },
{ "day": "2026-11-17", "engine": "perplexity", "samples": 3, "usd": 0.105 }
]
}Engine health
GET /v1/healthno token
Success rate and p95 latency (successful answers only) per engine over the last 24 hours, one entry per engine. Cached for 60 seconds.
curl https://api.sagbot.app/v1/health
{
"window_hours": 24,
"engines": [
{ "engine": "chatgpt", "status": "ok", "success_rate": 0.98, "p95_ms": 41000 }
]
}Errors and limits
Errors use the shared shape { "error": { "code", "message" } }.
| Status | code | When |
|---|---|---|
| 400 | invalid_request | Bad body, parameter or Idempotency-Key; the message says which |
| 401 | unauthorized | Missing, unknown or revoked token |
| 402 | insufficient_balance | The check costs more than your balance; top up and retry with a new Idempotency-Key |
| 404 | not_found | Unknown check id, or a check that isn't yours |
| 413 | body_too_large | Body over 16 KB |
| 429 | rate_limited | Too many requests; wait a minute |
Limits: 10 paid checks a minute per token (dry runs don't count), and 60 authenticated requests a minute per IP address.