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 cheapest path — 2¢ per call, 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	`$0.02`	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	`$0.25`	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	`$0.10`	Live ChatGPT UI capture with fan-out queries (the platform's web-search expansions), brand entities, citations, and answer text.
`gemini_live`optional	`$0.10`	Live Gemini UI capture with related-search fan-out, brand entities, citations, and answer text.
`ai_overview`optional	`$0.05`	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	`$0.10`	Google's AI Mode (the new conversational AI search surface) with citations and items markdown.
`bing_copilot`optional	`$0.05`	Bing Search with Copilot's AI Overview item + references. Also <5s p95.
`all_live`optional	`$0.50`	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) × 50¢.
`realistic`optional	`$0.25`	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. Q3 2026 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. 'us' default. Default: `us`
`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.

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": [], "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": [], "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": 2,
  "balance_after_cents": 9998,
  "cache_hit": false
}

Response — mode:all_live

Six platform slots populated in parallel. brand_entities is surfaced where the platform exposes it (chatgpt_live, gemini_live).fan_out is non-empty on the *_live modes that surface fan-out queries.

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"}] },
    "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": [] },
    "ai_mode":      { "mentioned": true, "rank": 2, "context": "...", "citations": [...5 items], "fan_out": [], "brand_entities": [] },
    "bing_copilot": { "mentioned": true, "rank": 4, "context": "...", "citations": [...7 items], "fan_out": [], "brand_entities": [] }
  },
  "created_at": "2026-04-25T12:00:30Z",
  "duration_ms": 28041,
  "cost_cents": 50,
  "balance_after_cents": 9948,
  "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": 25,
  "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" }
      ]
    }
  },
  "cost_cents": 10,
  "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": []
    }
  },
  "cost_cents": 5,
  "duration_ms": 3402,
  "cache_hit": false
}

Response — roadmap mode (501)

json

{
  "error": "mode_roadmap",
  "mode": "deep",
  "eta": "Q3 2026",
  "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`	Cents charged for this call (after partial-success refund).
`X-Balance-After-Cents`optional	`number`	Wallet balance in cents after the deduction.
`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.
`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.

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) × $0.50 = $0.33. 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 X-Balance-After-Cents header is always the final post-refund value.

Quickstart

Modes & pricing

Request body

Response — mode:quick

Response — mode:all_live

Response — mode:perplexity_live

Response — mode:chatgpt_live

Response — mode:ai_overview

Response — roadmap mode (501)

Response headers

Idempotency

Error codes

Partial-success refunds

Per-mode reference pages