POST /v1/check

The headline endpoint. Send a query + brand + mode and get back a per-platform report: whether the brand was mentioned, its rank, surrounding context, citations, and (where available) fan-out queries and brand entities.

POST/v1/check— Check whether a brand is mentioned across 8 AI search surfaces

Quickstart

Copy-paste, replace your API key, run. Default mode is quick (the headline mode — 150 credits per fresh call, 5 cached, 4 LLM APIs in parallel).

bash

curl https://api.mentionsapi.com/v1/check \
  -H "Authorization: Bearer lvk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "quick",
    "query": "best CRM for small business",
    "brand": "HubSpot"
  }'

Modes & pricing

Eight shippable modes, two roadmap modes. Pick the surface (or surfaces) you need; partial-success refund applies on every mode that fans out across multiple platforms.

Field	Type	Description
`quick` required	`150 credits`	Official LLM APIs (ChatGPT/OpenAI, Claude/Anthropic, Gemini/Google, Perplexity Sonar) in parallel. Returns brand mention + rank + the citations each API surfaces. Fastest path. Default.
`perplexity_live`optional	`85 credits`	Live UI scrape of perplexity.ai. Returns the answer real users see, plus 5–10 inline citations and 3–5 'related queries' fan_out items.
`chatgpt_live`optional	`35 credits`	Live ChatGPT UI capture with fan-out queries (the platform's web-search expansions), brand entities, citations, and answer text.
`gemini_live`optional	`35 credits`	Live Gemini UI capture with related-search fan-out, brand entities, citations, and answer text.
`ai_overview`optional	`15 credits`	Google Search with AI Overview block expanded — surfaces the AIO text + the references Google attributes to it. Cheapest live mode; <5s p95 latency.
`ai_mode`optional	`35 credits`	Google's AI Mode (the new conversational AI search surface) with citations and items markdown.
`bing_copilot`optional	`15 credits`	Bing Search with Copilot's AI Overview item + references. Also <5s p95.
`all_live`optional	`165 credits`	Composed bundle: runs perplexity_live + chatgpt_live + gemini_live + ai_overview + ai_mode + bing_copilot in parallel via a single call. Partial-failure refund applies — if k of 6 succeed, you pay (k/6) × 165 credits.
`realistic`optional	`85 credits`	DEPRECATED ALIAS for perplexity_live. Same path, same price. Will be removed in a future major version.
`deep`optional	`501 mode_roadmap`	ROADMAP. Multi-run variance + Wilson CI95 + API-vs-UI delta. Returns 501 today. Q1 2027 target.
`change_track`optional	`501 mode_roadmap`	ROADMAP. Scheduled brand-rank watches with diff. Use POST /v1/watch with mode:quick or mode:all_live for hourly polling in the meantime.

Request body

Field	Type	Description
`query` required	`string`	The natural-language question. 1–500 chars. Example: 'best CRM for small business'.
`brand` required	`string`	The brand name to look for in answers. 1–100 chars. Case-insensitive substring match plus Levenshtein-≤2 fuzzy match. Example: 'HubSpot'.
`mode` required	`string`	One of the 8 shippable modes above, or the deprecated 'realistic' alias. Roadmap modes ('deep' \| 'change_track') return 501.
`providers`optional	`string[]`	Which LLMs to query in mode:quick. Allowed: 'chatgpt' \| 'claude' \| 'gemini' \| 'perplexity'. Defaults to all 4. Ignored by every live mode (each live mode is single-platform; mode:all_live always fans out to all 6). Default: `['chatgpt','claude','gemini','perplexity']`
`region`optional	`string`	Two-letter region code (us, uk, ca, au). Routes the live modes to the matching geo-IP pool. In mode:quick, regional grounding is applied on ChatGPT, Claude and Perplexity. Gemini uses global grounding — the region parameter does not alter Gemini results. 'us' default. Default: `us`
`city`optional	`string`	Free-text city, 1–80 chars (e.g. 'Austin'). Localises web search to that city for the engines that support it — ChatGPT and Claude in mode:quick. Ignored by Gemini, Perplexity and every live mode. Combine with region for the country. A city-localised answer is cached separately from the country-only one.
`models`optional	`{ chatgpt?, claude?, gemini?, perplexity? }`	mode:quick only. Per-provider model override, e.g. { "chatgpt": "gpt-5", "claude": "claude-sonnet-5" }. Each model id (≤80 chars) is checked against the models currently available for that provider; an unknown model returns 400 invalid_model before anything is charged. Omitted providers use the default model. Reasoning models (gpt-5 family, o-series, sonar-reasoning) are allowed — forced web search is only applied to models that support it. Unknown keys are rejected.
`include`optional	`string[]`	Optional response enrichers: 'citations' \| 'fan_out' \| 'branding' \| 'raw'. 'citations' is included by default.

Response — mode:quick

200 OK with one entry per requested LLM provider. Failures surface in a separate errors block — the call still 200s, you only pay for successful providers. Citations carry an optional text field — the span of the answer the citation supports (≤300 chars) — when the engine reports one (ChatGPT and Gemini today); it is omitted otherwise.

json

{
  "request_id": "req_01JBQ2K8H...",
  "id": "chk_a8d2c...",
  "mode": "quick",
  "query": "best CRM for small business",
  "brand": "HubSpot",
  "providers": {
    "chatgpt": { "mentioned": true, "rank": 6, "context": "Top picks include HubSpot CRM...", "citations": [{"url":"https://zapier.com/blog/best-crms/","title":"Zapier","text":"HubSpot CRM stands out for its free tier"}], "fan_out": [] },
    "claude":  { "mentioned": true, "rank": 4, "context": "...", "citations": [{"url":"https://www.hubspot.com/crm","title":"hubspot.com"}], "fan_out": [] },
    "gemini":  { "mentioned": true, "rank": 7, "context": "...", "citations": [{"url":"https://www.g2.com/categories/crm","title":"G2 CRM Reviews","text":"HubSpot is a top-rated CRM for small teams"}], "fan_out": [] },
    "perplexity": { "mentioned": true, "rank": 6, "context": "...", "citations": [{"url":"https://zapier.com/blog/best-crms/","title":"Zapier"}], "fan_out": [] }
  },
  "created_at": "2026-04-25T12:00:00Z",
  "duration_ms": 4218,
  "cost_cents": 150,
  "balance_after_cents": 9870,
  "cache_hit": false
}

Per-provider result fields

Field	Type	Description
`mentioned`optional	`boolean`	Whether the brand appeared in the answer.
`rank`optional	`number \| null`	1-indexed position of the brand in the answer; null when not mentioned.
`context`optional	`string`	Sentence-level excerpt around the mention.
`citations`optional	`{ url, title, text?, branding? }[]`	Sources the surface attributed the answer to. text is the quoted span of the answer the citation supports (≤300 chars), present in mode:quick for ChatGPT and Gemini when reported. branding is only present with include: ['branding'].
`fan_out`optional	`string[]`	Sub-queries the surface expanded to. Always empty in mode:quick; populated by the live modes that expose them.
`brand_entities`optional	`{ name, domain?, description? }[]`	Live modes only — brand entities the surface recognised in the answer.
`sponsored`optional	`{ advertiser, title, url, domain, rendered }[]`	Paid placements shown alongside the answer. Present (possibly empty) on chatgpt_live, ai_overview, ai_mode and bing_copilot, and on those slots inside all_live — an empty array means 'checked, no sponsored placement'. Omitted on quick, gemini_live and perplexity_live, whose surfaces have no ad slot. rendered is true when the ad was actually displayed in the answer, false when it was served but not shown. Sponsored placements never feed mentioned, rank, context or citations — use this field to tell 'a competitor is buying ads on my prompt' apart from 'the engine recommends them'.
`surface_present`optional	`boolean`	Live modes only — false when the surface showed no AI answer for this query at all. Omitted when an answer existed.
`raw`optional	`string`	Full answer text. Only present with include: ['raw'].

Response — mode:all_live

Six platform slots populated in parallel. brand_entities is surfaced where the platform exposes it (chatgpt_live, gemini_live). sponsored lists the paid placements shown with the answer on the chatgpt, ai_overview, ai_mode and bing_copilot slots (an empty array means none were shown; ads never count as mentions). fan_out is non-empty on the *_live modes that surface fan-out queries. On live surface modes a slot may also carry surface_present: false — the surface showed no AI answer for this query (e.g. Google rendered no AI Overview). That is distinct from mentioned: false, which means an answer existed but your brand wasn't in it. The field is omitted when the surface produced an answer.

json

{
  "request_id": "req_01JBQ2K8H...",
  "id": "chk_a8d2c...",
  "mode": "all_live",
  "query": "best CRM for small business",
  "brand": "HubSpot",
  "providers": {
    "perplexity":   { "mentioned": true, "rank": 6, "context": "...", "citations": [...10 items], "fan_out": [...5 items] },
    "chatgpt":      { "mentioned": true, "rank": 4, "context": "...", "citations": [...4 items], "fan_out": [...3 items], "brand_entities": [{"name":"HubSpot","domain":"hubspot.com"}], "sponsored": [{"advertiser":"Salesforce","title":"Salesforce Starter Suite","url":"https://www.salesforce.com/starter/","domain":"salesforce.com","rendered":true}] },
    "gemini":       { "mentioned": true, "rank": 5, "context": "...", "citations": [...6 items], "fan_out": [...4 items], "brand_entities": [...] },
    "ai_overview":  { "mentioned": true, "rank": 3, "context": "...", "citations": [...8 items], "fan_out": [], "brand_entities": [], "sponsored": [] },
    "ai_mode":      { "mentioned": true, "rank": 2, "context": "...", "citations": [...5 items], "fan_out": [], "brand_entities": [], "sponsored": [] },
    "bing_copilot": { "mentioned": true, "rank": 4, "context": "...", "citations": [...7 items], "fan_out": [], "brand_entities": [], "sponsored": [] }
  },
  "created_at": "2026-04-25T12:00:30Z",
  "duration_ms": 28041,
  "cost_cents": 165,
  "balance_after_cents": 9705,
  "cache_hit": false
}

Response — mode:perplexity_live

json

{
  "request_id": "req_01JBQ2K8H...",
  "id": "chk_a8d2c...",
  "mode": "perplexity_live",
  "providers": {
    "perplexity": {
      "mentioned": true, "rank": 6,
      "context": "If you want a free-tier and strong sales/marketing features: HubSpot CRM...",
      "citations": [
        { "url": "https://zapier.com/blog/best-crms-for-small-business/", "title": "The 12 best CRMs for small business" },
        { "url": "https://www.softwareadvice.com/crm/", "title": "CRM Software Reviews" }
      ],
      "fan_out": [
        "What features matter most for my small business CRM",
        "CRM comparisons by price for small businesses in 2026"
      ]
    }
  },
  "cost_cents": 85,
  "duration_ms": 25102,
  "cache_hit": false
}

Response — mode:chatgpt_live

json

{
  "request_id": "req_01JBQ2K8H...",
  "id": "chk_a8d2c...",
  "mode": "chatgpt_live",
  "providers": {
    "chatgpt": {
      "mentioned": true, "rank": 6,
      "context": "Among the top picks for small businesses, HubSpot CRM stands out for its free tier...",
      "citations": [
        { "url": "https://www.g2.com/categories/crm", "title": "G2 CRM Reviews" }
      ],
      "fan_out": [
        "best free CRM 2026",
        "HubSpot vs Salesforce small business",
        "CRM features startups need"
      ],
      "brand_entities": [
        { "name": "HubSpot", "domain": "hubspot.com", "description": "Free CRM with marketing/sales suite" },
        { "name": "Salesforce", "domain": "salesforce.com" }
      ],
      "sponsored": [
        { "advertiser": "Salesforce", "title": "Salesforce Starter Suite — CRM for small business", "url": "https://www.salesforce.com/starter/", "domain": "salesforce.com", "rendered": true }
      ]
    }
  },
  "cost_cents": 35,
  "duration_ms": 22418,
  "cache_hit": false
}

Response — mode:ai_overview

json

{
  "request_id": "req_01JBQ2K8H...",
  "id": "chk_a8d2c...",
  "mode": "ai_overview",
  "providers": {
    "ai_overview": {
      "mentioned": true, "rank": 3,
      "context": "...HubSpot offers a free CRM with strong marketing automation features...",
      "citations": [
        { "url": "https://www.hubspot.com/crm", "title": "HubSpot — hubspot.com" },
        { "url": "https://blog.hubspot.com/sales/free-crm-software", "title": "Free CRM Software" }
      ],
      "fan_out": [],
      "brand_entities": [],
      "sponsored": []
    }
  },
  "cost_cents": 15,
  "duration_ms": 3402,
  "cache_hit": false
}

Response — unknown model override (400)

Returned before anything is charged when a models entry names a model that is not available for its provider.

json

{
  "error": {
    "code": "invalid_model",
    "message": "gpt-9 is not available for chatgpt",
    "provider": "chatgpt",
    "model": "gpt-9"
  },
  "request_id": "req_01JBQ2K8H..."
}

Response — roadmap mode (501)

json

{
  "error": "mode_roadmap",
  "mode": "deep",
  "eta": "Q1 2027",
  "available_modes": ["quick","perplexity_live","chatgpt_live","gemini_live","ai_overview","ai_mode","bing_copilot","all_live"],
  "message": "Deep mode (multi-run variance + delta) is on the roadmap. Use mode:quick for cheap baseline polling, any mode:*_live for ground-truth UI scraping, or mode:all_live for a single-call bundle of all 6 surfaces.",
  "request_id": "req_01JBQ2K8H..."
}

Response headers

Field	Type	Description
`X-Request-ID`optional	`string`	Echo of the request_id assigned by the gateway.
`X-Mode`optional	`string`	The mode that ran. The deprecated `realistic` alias surfaces here as the canonical `perplexity_live`.
`X-Cost-Cents`optional	`number`	Credits charged for this call (after partial-success refund).
`X-Balance-After-Cents`optional	`number`	Credit balance after this call.
`X-Cache-Status`optional	`string`	'hit-l1' \| 'hit-l2' \| 'miss'. Cache hits return identical payloads at zero additional latency.
`X-RateLimit-Limit`optional	`number`	Token-bucket capacity for the (api_key, mode) pair.
`X-RateLimit-Remaining`optional	`number`	Tokens remaining in the bucket.
`Retry-After`optional	`number`	Only on 429. Seconds until the bucket has at least one token again.

Idempotency

Pass an Idempotency-Key header (1–200 chars). Replays within 24h return the original response verbatim with Idempotency-Replay: true and DO NOT re-deduct your wallet. A request body that differs from the original returns 422 with idempotency_body_mismatch.

bash

curl https://api.mentionsapi.com/v1/check \
  -H "Authorization: Bearer lvk_live_..." \
  -H "Idempotency-Key: my-job-2026-04-25-001" \
  -H "Content-Type: application/json" \
  -d '{"mode":"all_live","query":"...","brand":"..."}'

Error codes

Field	Type	Description
`400 invalid_request`optional	`Error`	Request body failed schema validation.
`400 invalid_model`optional	`Error`	mode:quick — a models entry names a model that is not available for its provider. Body includes provider + model. Nothing is charged.
`401 missing_authorization`optional	`Error`	Missing or malformed Authorization header. Expected: 'Bearer lvk_live_...'.
`402 insufficient_balance`optional	`Error`	Wallet balance is below this call's price. Body includes balance_cents + required_cents + topup_url.
`422 idempotency_body_mismatch`optional	`Error`	Reusing an Idempotency-Key with a different request body.
`429 rate_limited`optional	`Error`	Per-mode token bucket exhausted.
`501 mode_roadmap`optional	`Error`	mode:deep or mode:change_track. See `eta` field for target ship date.
`501 mode_not_yet_available`optional	`Error`	Live-mode infrastructure not configured on this deployment.
`503 upstream_unavailable`optional	`Provider error`	An upstream surface returned an error (per-platform, surfaced under errors[platform]).
`503 upstream_rate_limited`optional	`Provider error`	An upstream surface rate-limited us. Per-platform; refund applied.
`503 upstream_timeout`optional	`Provider error`	An upstream surface timed out before returning a response. Per-platform.
`surface_unavailable_in_region`optional	`Provider error`	Live surface modes only: the requested AI surface is not available in the requested region (e.g. AI Mode hasn't launched there). Surfaced under errors[platform]; the call still 200s and the failed platform is refunded. Not retryable with the same region.

Full error catalog at /docs/errors.

Partial-success refunds

Every multi-platform mode prorates the price. If you call mode:all_live and 4 of 6 platforms return, you pay (4 / 6) × 165 = 110 credits. If 0 platforms return, the refund is 100% — you only pay for what worked. The same proration applies to mode:quick when one of 4 LLM APIs fails. The difference is credited back to your wallet automatically (a partial-result credit — no support ticket needed), and cached repeats settle at the cached price automatically. The X-Balance-After-Cents header is always the final post-refund value.

Quickstart

Modes & pricing

Request body

Response — mode:quick

Per-provider result fields

Response — mode:all_live

Response — mode:perplexity_live

Response — mode:chatgpt_live

Response — mode:ai_overview

Response — unknown model override (400)

Response — roadmap mode (501)

Response headers

Idempotency

Error codes

Partial-success refunds

Per-mode reference pages