GET /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

Query parameters

  • date_from string optional

    Start of the period, inclusive (ISO-8601). Defaults to 30 days before date_to.

  • date_to string optional

    End of the period, exclusive (ISO-8601). Defaults to now.

  • scheduled_report_id string optional

    Only the runs of this Scheduled Report (UUID).

  • tracker_id string optional

    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.

  • market_id string optional

    Only the runs in these markets (a report's market_id, a region config's id); repeat the parameter for several.

  • place string optional

    Only the runs in these places, as country|city lowercased (united states|austin, or united states| for the whole country; country|city|region for a town keyed apart from its namesake, australia|emerald|victoria), across every tracker; repeat the parameter for several.

  • scope string optional

    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) or all (every completed report). Takes no tracker, market, place or schedule filter.

  • platform string optional

    Only answers from these engines; repeat the parameter for several.

  • category string optional

    The relations counted; repeat for several (category=direct_competitor&category=publisher). Direct and indirect competitors when left out.

  • limit integer optional

    Page size (1-500).

    default: 100

  • offset integer optional

    Rows to skip.

    default: 0

  • dry_run boolean optional

    Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns 200 with a dry_run object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns 422.

    default: false

Responses

Competitor share of voice application/json
Type: CompetitorSummary
  • answers integer required

    AI answers under the filters.

    min: 0

  • data array of CompetitorShare required

    This page of the brand (first) and its competitors, most mentioned first.

  • date_from string required

    Start of the period, inclusive.

    format: `date-time`

  • date_to string required

    End of the period, exclusive.

    format: `date-time`

  • has_more boolean required

    True when more rows exist past this page.

  • limit integer required

    Page size that was applied.

    min: 1

  • offset integer required

    Rows skipped before this page.

    min: 0

  • total integer required

    Rows under the filters across all pages, the brand's included.

    min: 0

  • object string

    Always competitor_summary.

    default: `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
}
Request validation failed application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response
{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Missing or invalid credentials application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
You do not have permission to access this resource application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response
{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource not found application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response
{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource conflict application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response
{
  "error": {
    "code": "conflict",
    "message": "Resource conflict"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Per-minute rate limit exceeded application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-minute rate limit exceeded"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
An unexpected error occurred application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Service temporarily unavailable, please retry application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response
{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable, please retry"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}