---
title: "Cumulative Share of Voice"
method: POST
path: "/api/v1/metrics/share-of-voice/cumulative"
tags: ["Metrics"]
---

# Cumulative Share of Voice

`POST /api/v1/metrics/share-of-voice/cumulative`

## Request

- Base URL: `https://api.athenahq.ai`
- URL: `https://api.athenahq.ai/api/v1/metrics/share-of-voice/cumulative`
- Auth: API key in header `x-api-key`

Returns aggregated share of voice percentages across the specified date range. Shows what percentage of AI responses mention your brand versus competitors. Each entry also includes `relative_mention_rate`: the entry's mentions as a percentage of responses that mention at least one tracked brand.

## Request body

- SOVRequest: Request body for share of voice endpoints
  - `website_id` string, uuid, required: The ID of the website to query share of voice for
  - `filters` MetricsApiFilters, required: Filters for the metrics endpoints: the shared response filters plus an optional saved view.
    - `schedule_id` union: Select one streaming schedule. Use the selection returned by GET /api/v1/prompt-schedules. Default includes all pre-cutover history and ad hoc runs; archived schedules retain results. The retired manual token is accepted as an alias of default. This field takes one schedule; a list returns 400.
      - 'default' | 'manual'
      - string, uuid
    - `start_date` string, date-time, required: Filter start date (UTC)
    - `end_date` string, date-time: Filter end date (UTC)
    - `models` string[]: Filter by AI models
    - `prompt_ids` string[]: Filter by specific prompt IDs
    - `competitor_ids` string[]: Filter by specific competitor IDs
    - `location_ids` string[]: Filter by location IDs. Pass this in the JSON body as `filters.location_ids`, even when filtering by a single location. Use IDs returned by `GET /api/v1/locations`.
    - `prompt_status` 'active' | 'paused': Filter by prompt status
    - `prompt_type` 'branded' | 'non_branded': Filter by prompt type
    - `saved_view_id` string, uuid: A saved view to apply, from `GET /api/v1/saved-views`. Its filters apply the way the dashboard applies them, including the dashboard's defaults of active prompts and every model. Any filter you also send replaces the view's value for that field. The view's saved date range is ignored: `start_date` and `end_date` decide the window. Returns `404` when the view is not on `website_id`, and `400` naming any view filter the API cannot apply, which you can replace by sending that filter explicitly.

## Response `200`

Successful response with share of voice data

- object
  - `data` CumulativeSOVEntry[], required
    - `name` string, required: Brand or competitor name
    - `value` number, required: Share of voice percentage (0-100)
    - `relative_mention_rate` number, required: Relative mention rate percentage (0-100): mentions of this brand/competitor divided by the number of responses that mention at least one tracked brand
    - `absolute_value` integer, required: Raw mention count
    - `is_self` boolean, required: True if this entry represents your tracked website

## Other responses

- `400`: Bad request - Invalid parameters
- `401`: Unauthorized - Invalid or missing API key
- `403`: Forbidden - You don't have access to this website
- `404`: Website not found
- `500`: Internal server error

## Changes

- **2026-11-03** `2d1d86d5e067`: 2 breaking, 8 warning
  - added `#/components/schemas/ApiFilters, subschema #2` to the `filters` request property `allOf` list
  - the `filters` request property type changed from `object` to no type
  - removed the request property `filters/competitor_ids`
  - removed the request property `filters/end_date`
  - …6 more

[Operation history](https://skmtc.dev/athenahq/apis/athenahq-api/changes/api/v1/metrics/share-of-voice/cumulative/post.md)

---

[API](https://skmtc.dev/athenahq/apis/athenahq-api.md) - [All operations](https://skmtc.dev/athenahq/apis/athenahq-api/llms.txt) - [OpenAPI document](https://skmtc.dev/athenahq/apis/athenahq-api/revisions/6cf9ca58edf6?raw)