Beta Enabled per account — contact us to turn it on.

POST /v1/share-of-voice

How much of the conversation each brand owns in AI answers. Send 1–5 brands and get, for each, how many AI answers mentioned it over the window, the AI search volume of the prompts behind those answers, and its share of the total — plus the domains those answers cite most. One call replaces hundreds of individual /v1/check runs when the question is “who is winning?” rather than “was I mentioned on this prompt?”.

POST/v1/share-of-voice— Mention share across up to 5 brands in AI answers (Beta)

Availability

This endpoint is in beta and is switched on per account. Accounts without it receive 501 feature_disabled before any authentication, balance check or charge. Email [email protected] with your account email to get access. The request and response shapes below are stable for the beta; additive fields may appear without notice (clients should ignore unknown fields, as everywhere else in the API).

Pricing — 350 credits / call

Flat per-call price regardless of how many brands (1–5) you send. Debited upfront; if the mentions dataset is unavailable the call returns 503 share_of_voice_unavailable and the full 350 credits are refunded automatically. The top-domains lookup is best-effort — if it fails, top_domains is empty and you are still charged for the brand metrics you received.

Quickstart

bash

curl https://api.mentionsapi.com/v1/share-of-voice \
  -H "Authorization: Bearer lvk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "brands": ["HubSpot", "Salesforce", "Pipedrive"],
    "region": "us",
    "window": "30d"
  }'

Request body

Field	Type	Description
`brands` required	`string[]`	1–5 brand names (or bare domains), 1–120 chars each, case-insensitively unique. The first brand is the one top_domains is computed for.
`region`optional	`string`	Two-letter country code (lower-cased). Example: 'us', 'gb', 'de'. Default: `us`
`window`optional	`'30d' \| '90d'`	Lookback window for the mention counts. Default: `'30d'`

Response

json

{
  "id": "req_01JBQ2K8H...",
  "request_id": "req_01JBQ2K8H...",
  "brands": [
    {
      "brand": "HubSpot",
      "mentions": 1840,
      "ai_search_volume": 52000,
      "impressions": null,
      "share": 0.46,
      "by_platform": {
        "chatgpt": { "mentions": 1210, "ai_search_volume": 31000 },
        "google":  { "mentions": 630,  "ai_search_volume": 21000 }
      }
    },
    {
      "brand": "Salesforce",
      "mentions": 1520,
      "ai_search_volume": 48000,
      "impressions": null,
      "share": 0.38,
      "by_platform": {
        "chatgpt": { "mentions": 980, "ai_search_volume": 27000 },
        "google":  { "mentions": 540, "ai_search_volume": 21000 }
      }
    },
    {
      "brand": "Pipedrive",
      "mentions": 640,
      "ai_search_volume": 17000,
      "impressions": null,
      "share": 0.16
    }
  ],
  "top_domains": [
    { "domain": "hubspot.com", "mentions": 412 },
    { "domain": "g2.com", "mentions": 198 },
    { "domain": "zapier.com", "mentions": 143 }
  ],
  "window": "30d",
  "region": "us",
  "cost_cents": 350,
  "balance_after_cents": 9650
}

Top-level fields

Field	Type	Description
`id`optional	`string`	Stable handle for this result (same value as request_id).
`brands`optional	`ShareOfVoiceBrand[]`	One entry per requested brand, in request order. See below.
`top_domains`optional	`{ domain: string, mentions: number }[]`	Up to 10 most-cited domains in answers that mention the FIRST brand in the request. Best-effort; empty when unavailable.
`window`optional	`'30d' \| '90d'`	Echo of the window used.
`region`optional	`string`	Echo of the region used.
`cost_cents`optional	`number`	Credits charged (350).
`balance_after_cents`optional	`number`	Credit balance after this call.

ShareOfVoiceBrand

Field	Type	Description
`brand`optional	`string`	The brand as you sent it.
`mentions`optional	`number`	Number of AI answers in the window that mention the brand.
`ai_search_volume`optional	`number \| null`	Aggregated AI search volume of the prompts those answers responded to. null when unavailable.
`impressions`optional	`null`	Reserved. Always null today.
`share`optional	`number`	0–1. This brand's fraction of the summed mentions across the brands in the request — relative to the request, not to the whole market. Shares across the brands array sum to 1 (modulo rounding).
`by_platform`optional	`{ [platform]: { mentions, ai_search_volume } }`	Per-platform breakdown when the dataset returns one (keys today: 'chatgpt', 'google'). Omitted otherwise.

Response — not enabled (501)

json

{
  "error": {
    "code": "feature_disabled",
    "message": "share-of-voice is not enabled on this account yet"
  }
}

Response — data unavailable (503, refunded)

json

{
  "request_id": "req_01JBQ2K8H...",
  "error": "share_of_voice_unavailable",
  "message": "Mentions data is temporarily unavailable. The call was not charged."
}

Error codes

Field	Type	Description
`400 invalid_request`optional	`Error`	Schema validation failed — e.g. more than 5 brands, a duplicate brand, or a region that is not a 2-letter code.
`401 missing_authorization`optional	`Error`	Missing or malformed Authorization header. Expected: 'Bearer lvk_live_...'.
`402 insufficient_balance`optional	`Error`	Balance below 350 credits.
`429 rate_limited`optional	`Error`	Per-key bucket exhausted. Retry-After header tells you when.
`501 feature_disabled`optional	`Error`	Share of voice is not enabled on this account. Returned before any charge. Contact [email protected].
`503 share_of_voice_unavailable`optional	`Error`	The mentions dataset was unavailable. The upfront charge is refunded in full; retry later.

Full error catalog at /docs/errors.

Notes

Share is relative to the request. Sending ["HubSpot"] alone returns share: 1. Add the competitors you care about to get a meaningful split.
Mention counts are aggregated across a dataset of AI-assistant answers (ChatGPT and Google AI surfaces), not produced by live checks — they describe the window as a whole. For a prompt-level, right-now answer, use /v1/check.
Pair with /v1/discover. /v1/discover tells you which prompts carry AI search volume; share of voice tells you who wins across them. Together they are the two halves of a competitive share-of-voice dashboard.
Idempotency: pass an Idempotency-Key header to replay a result within 24h without re-charging.