/v1/brands/{brand_id}/competitors/summary Competitor share of voice
Share of voice of the brand and its competitors, the numbers the Competitors page shows under the same filters: per entity the answers naming it, its percent of all mentions, its change from the older half of the runs to the newer, its engines, whether it is new and how many answers named it without the brand. Competitors are read through the directory: an alias counts under its competitor's name and a removed competitor is left out.
The period defaults to the 30 days before date_to, and date_to to now. With no tracker_id, market_id, place or scheduled_report_id it reads what the page opens on (scope=default); scope=all reads every completed report. platform keeps answers from those engines. Offset-paginated: the brand first, then the competitors most mentioned first; shares are over every entity under the filters, not only the page.
Path parameters
-
Brand UUID.
Query parameters
-
Start of the period, inclusive (ISO-8601). Defaults to 30 days before
date_to. -
End of the period, exclusive (ISO-8601). Defaults to now.
-
Only the runs of this Scheduled Report (UUID).
-
Only the runs of these trackers (a report's
tracker_id; a scheduled report's id is its tracker's); repeat the parameter for several. -
Only the runs in these markets (a report's
market_id, a region config'sid); repeat the parameter for several. -
Only the runs in these places, as
country|citylowercased (united states|austin, orunited states|for the whole country;country|city|regionfor a town keyed apart from its namesake,australia|emerald|victoria), across every tracker; repeat the parameter for several. -
default(what the page opens on: every scheduled report's runs plus the newest one-off reports, and the default when no tracker, market, place or schedule is given) orall(every completed report). Takes no tracker, market, place or schedule filter. -
Only answers from these engines; repeat the parameter for several.
-
The relations counted; repeat for several (
category=direct_competitor&category=publisher). Direct and indirect competitors when left out. -
Page size (1-500).
default: 100
-
Rows to skip.
default: 0
-
Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns
200with adry_runobject reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns422.default: false
Responses
-
AI answers under the filters.
-
This page of the brand (first) and its competitors, most mentioned first.
-
Start of the period, inclusive.
-
End of the period, exclusive.
-
True when more rows exist past this page.
-
Page size that was applied.
-
Rows skipped before this page.
-
Rows under the filters across all pages, the brand's included.
- object string
Always
competitor_summary.
Example response
{
"answers": 412,
"data": [
{
"answers_without_brand": 41,
"category": "direct_competitor",
"change": 2.5,
"is_brand": false,
"is_new": false,
"key": "asics",
"mentions": 118,
"name": "ASICS",
"object": "competitor_share",
"platform_share": {
"chatgpt": 34,
"gemini": 30.2,
"perplexity": 29.8
},
"platforms": [
"chatgpt",
"gemini",
"perplexity"
],
"share": 31.4,
"website": "https://www.asics.com"
}
],
"date_from": "2026-08-21T00:00:00+00:00",
"date_to": "2026-09-20T00:00:00+00:00",
"has_more": false,
"limit": 100,
"object": "competitor_summary",
"offset": 0,
"total": 1
}-
Show fields
-
Stable machine-readable error code from the catalog.
-
Human-readable description suitable for logging.
- details object
Optional, code-specific context (e.g.
errorsarray forvalidation_error,retry_afterforservice_unavailable). Shape depends onerror.code; treat as opaque otherwise.Show fields
Empty object (no properties).
-
- request_id string
Server-generated correlation id for the request. Mirrors the
X-Correlation-IDresponse header. Include this when contacting support.
Example response
{
"error": {
"code": "validation_error",
"message": "Request validation failed"
},
"request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}-
Show fields
-
Stable machine-readable error code from the catalog.
-
Human-readable description suitable for logging.
- details object
Optional, code-specific context (e.g.
errorsarray forvalidation_error,retry_afterforservice_unavailable). Shape depends onerror.code; treat as opaque otherwise.Show fields
Empty object (no properties).
-
- request_id string
Server-generated correlation id for the request. Mirrors the
X-Correlation-IDresponse header. Include this when contacting support.
Example response
{
"error": {
"code": "unauthorized",
"message": "Missing or invalid credentials"
},
"request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}-
Show fields
-
Stable machine-readable error code from the catalog.
-
Human-readable description suitable for logging.
- details object
Optional, code-specific context (e.g.
errorsarray forvalidation_error,retry_afterforservice_unavailable). Shape depends onerror.code; treat as opaque otherwise.Show fields
Empty object (no properties).
-
- request_id string
Server-generated correlation id for the request. Mirrors the
X-Correlation-IDresponse header. Include this when contacting support.
Example response
{
"error": {
"code": "forbidden",
"message": "You do not have permission to access this resource"
},
"request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}-
Show fields
-
Stable machine-readable error code from the catalog.
-
Human-readable description suitable for logging.
- details object
Optional, code-specific context (e.g.
errorsarray forvalidation_error,retry_afterforservice_unavailable). Shape depends onerror.code; treat as opaque otherwise.Show fields
Empty object (no properties).
-
- request_id string
Server-generated correlation id for the request. Mirrors the
X-Correlation-IDresponse header. Include this when contacting support.
Example response
{
"error": {
"code": "not_found",
"message": "Resource not found"
},
"request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}-
Show fields
-
Stable machine-readable error code from the catalog.
-
Human-readable description suitable for logging.
- details object
Optional, code-specific context (e.g.
errorsarray forvalidation_error,retry_afterforservice_unavailable). Shape depends onerror.code; treat as opaque otherwise.Show fields
Empty object (no properties).
-
- request_id string
Server-generated correlation id for the request. Mirrors the
X-Correlation-IDresponse header. Include this when contacting support.
Example response
{
"error": {
"code": "conflict",
"message": "Resource conflict"
},
"request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}-
Show fields
-
Stable machine-readable error code from the catalog.
-
Human-readable description suitable for logging.
- details object
Optional, code-specific context (e.g.
errorsarray forvalidation_error,retry_afterforservice_unavailable). Shape depends onerror.code; treat as opaque otherwise.Show fields
Empty object (no properties).
-
- request_id string
Server-generated correlation id for the request. Mirrors the
X-Correlation-IDresponse header. Include this when contacting support.
Example response
{
"error": {
"code": "rate_limit_exceeded",
"message": "Per-minute rate limit exceeded"
},
"request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}-
Show fields
-
Stable machine-readable error code from the catalog.
-
Human-readable description suitable for logging.
- details object
Optional, code-specific context (e.g.
errorsarray forvalidation_error,retry_afterforservice_unavailable). Shape depends onerror.code; treat as opaque otherwise.Show fields
Empty object (no properties).
-
- request_id string
Server-generated correlation id for the request. Mirrors the
X-Correlation-IDresponse header. Include this when contacting support.
Example response
{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred"
},
"request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}-
Show fields
-
Stable machine-readable error code from the catalog.
-
Human-readable description suitable for logging.
- details object
Optional, code-specific context (e.g.
errorsarray forvalidation_error,retry_afterforservice_unavailable). Shape depends onerror.code; treat as opaque otherwise.Show fields
Empty object (no properties).
-
- request_id string
Server-generated correlation id for the request. Mirrors the
X-Correlation-IDresponse header. Include this when contacting support.
Example response
{
"error": {
"code": "service_unavailable",
"message": "Service temporarily unavailable, please retry"
},
"request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}