---
title: "Get rolling share of voice time series and breakdowns"
method: GET
path: "/api/v1/analytics/sov/timeseries"
tags: ["Visibility & Mentions"]
---

# Get rolling share of voice time series and breakdowns

`GET /api/v1/analytics/sov/timeseries`

## Request

- Base URL: `https://app.promptingco.com`
- URL: `https://app.promptingco.com/api/v1/analytics/sov/timeseries`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer
  - API key in cookie `better-auth.session_token`

## Query parameters

- `productId` string: Product ID to use as the primary SOV scope.
- `brandId` string: Deprecated. Use productId instead. Product ID to use as the primary SOV scope.
- `by` 'prompt' | 'topic' | 'engine' | 'competitor' | 'sentiment'
- `viewId` string: View ID to scope results to the view's prompts. Not supported with by=topic or topicId.
- `promptId` string
- `topicId` string
- `engine` string
- `regionId` string
- `granularity` 'day' | 'week' | 'month': UTC calendar bucket used for time-series points and as the unit for rollingWindow. Week buckets start on Monday.
- `rollingWindow` integer: Number of granularity buckets included in each time-series point. Accepts 1 through 30 and defaults to 30.
- `start` string: Selects the earliest calendar bucket returned. Must be supplied with end. For week or month granularity, the containing bucket starts before this date and includes those earlier dates in its rolling calculation.
- `end` string: Selects the latest calendar bucket returned. Must be supplied with start. For week or month granularity, the containing bucket is returned with data accumulated only through this date.
- `pinned` boolean: Only valid with by=competitor. When true, return only the product's pinned competitors' SoV (paginated over the pinned subset).
- `page` integer
- `pageSize` integer
- `sortBy` 'sov' | 'mentions' | 'runs' | 'label'
- `sortDirection` 'asc' | 'desc'

## Response `200`

Successful response

- object
  - `ok` true, required
  - `data` object, required
    - `scope` object, required
      - `product` object, required
        - `id` string, required
        - `name` string, required
        - `slug` string, required
    - `pagination` object, required
      - `page` integer, required
      - `pageSize` integer, required
      - `total` integer, required
      - `totalPages` integer, required
    - `sort` object, required
      - `sortBy` 'sov' | 'mentions' | 'runs' | 'label'
      - `sortDirection` 'asc' | 'desc'
      - `sortableDimensions` string[], required
    - `calculation` object, required
      - `type` 'trailing_ratio', required
      - `granularity` 'day' | 'week' | 'month', required
      - `rollingWindow` integer, required
      - `timezone` 'UTC', required
    - `timeSeries` object[], required: Trailing-window snapshots for calendar buckets that intersect start and end. Each point is labeled by its UTC bucket-start date, and the calculation object identifies the applied window.
      - `date` string, required: UTC start date of the day, week, or month bucket represented by this point.
      - `sov` number, required: Share of voice percentage from 0 through 100.
      - `mentions` integer, required
      - `runs` integer, required
    - `products` object[], required
      - `product_id` string, required
      - `product_name` string, required
      - `sov` number, required
      - `mentions` integer, required
      - `runs` integer, required
      - `date` string
    - `rows` object[], required
      - `dimension` 'product' | 'prompt' | 'topic' | 'engine' | 'competitor' | 'sentiment', required
      - `key` string, required
      - `label` string, required
      - `date` string
      - `sov` number, required
      - `mentions` integer, required
      - `runs` integer, required
      - `rank` integer

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Forbidden
- `404`: Not found
- `422`: Validation failed
- `500`: Internal server error

---

[API](https://skmtc.dev/promptingcompany/apis/the-prompting-company-api.md) - [All operations](https://skmtc.dev/promptingcompany/apis/the-prompting-company-api/llms.txt) - [OpenAPI document](https://skmtc.dev/promptingcompany/apis/the-prompting-company-api/revisions/c0451ea10e9a?raw)