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

  1. POST /v1/check with 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).
  2. Poll GET /v1/checks/{id} until it finishes. Each engine answers samples times; failed answers are refunded automatically.
  3. 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 idLabelSurfacePer answer
chatgptChatGPTui$0.035
google_aioGoogle AI Overviewsui$0.035
geminiGeminiui$0.035
google_ai_modeGoogle AI Modeui$0.035
perplexityPerplexityapi$0.035
claudeClaudeapi$0.06
chatgpt_apiChatGPT (API)api$0.06
gemini_apiGemini (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/engines

Create a check

POST /v1/check202, or 200 for a dry run

FieldTypeDescription
querystring, requiredThe question, 1 to 300 characters
brand.namestring, required1 to 100 characters
brand.domainstringA host such as sagbot.app; citations on it or its subdomains count as cited
brand.aliasesstring[]Other names of the brand, up to 10
competitorsstring[]Up to 10 names, each reported with its own rates
enginesstring[]Distinct engine ids. Default: the five default engines
countrystringISO 3166-1 alpha-2, default US. The list is in openapi.yaml
languagestringISO 639-1, optionally with a region (en, pt-BR). Default en
samplesinteger1 to 5, default 1. More samples give a mention rate with a narrower interval
includestring[]["raw"] adds each answer's text to the result
dry_runbooleantrue 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.

FieldDescription
surfaceui or api, as in the engine catalog
modelThe model the supplier reported (or the engine id); null only when no answer succeeded
samples, samples_okAnswers asked for, and answers that came back
mentioned_rateShare of answers that mention the brand (or an alias)
ci95Wilson 95% interval of mentioned_rate
cited_rateShare of answers citing brand.domain
avg_positionMean rank of the brand's first mention among brand and competitors; 1 = first
surface_present_rateShare of answers where the surface appeared at all (Google shows no AI Overview for many queries)
web_search_rateShare of answers where the model searched the web; null when the supplier doesn't say (UI engines)
sample_flagsPer answer: no_web_search and no_citations, so "not cited" is never read as "didn't search"
fan_outThe web searches the engine ran to answer; empty when it doesn't report them
competitorsname, mentioned_rate, avg_position per competitor
citationsCited URLs, most cited first: url, title, domain, count (answers citing it), brand (on brand.domain)
errorsFailed answers: sample and code (timeout or upstream_error); each was refunded
rawOnly 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" } }.

StatuscodeWhen
400invalid_requestBad body, parameter or Idempotency-Key; the message says which
401unauthorizedMissing, unknown or revoked token
402insufficient_balanceThe check costs more than your balance; top up and retry with a new Idempotency-Key
404not_foundUnknown check id, or a check that isn't yours
413body_too_largeBody over 16 KB
429rate_limitedToo 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.