Share of voice: your brand vs competitors
Relevant mention counts for every keyword tagged own_brand or competitor over an inclusive YYYY-MM-DD window (default: the last 30 days), with each keyword’s share of all brand mentions and your brand’s combined share (ownBrandShare). A mention that matched both your brand and a competitor counts for each. hasCompetitors=false means no keyword is tagged competitor yet.
Authorizations
Clerk API key. Create one in Settings → API Keys. Pass as Authorization: Bearer <key>. Keys carry a scope — read, write (implies read) or admin (implies write) — chosen when the key is minted. Each operation's security requirement (and its x-required-scope extension) names the minimum scope it needs; request the least-privileged key that covers the operations you call.
Query Parameters
Numeric ids of the monitored keywords to scope to (from list_keywords). Omit for every keyword. A mention that matched several keywords counts once per keyword in per-keyword breakdowns and once in totals.
0 < x <= 9007199254740991Inclusive first day of the window as YYYY-MM-DD (UTC) — NEVER an ISO timestamp with T/Z. Omit for the default: the last 30 days ending today.
^\d{4}-\d{2}-\d{2}$Inclusive last day of the window as YYYY-MM-DD (UTC). Omit for today. Must be on or after startDate; the window may span at most 365 days.
^\d{4}-\d{2}-\d{2}$Response
200 response
Share (0–100, one decimal) of brand mentions that matched an own_brand keyword. null when the window has no brand mentions at all.
Sum of count over every row — a mention that matched both your brand and a competitor counts once for each, so it is the denominator of every share.
-9007199254740991 <= x <= 9007199254740991At least one keyword is tagged own_brand.
At least one keyword is tagged competitor. Without one, share of voice has nothing to compare against — tag competitor keywords first.
One row per tagged keyword in scope (zero-count keywords included), sorted by count desc.
