Position time-series

Returns the average position of each tracked brand within the answers that mention it, bucketed by interval. Position counts the brands in the order they appear in an answer, so a lower number is a more prominent placement and 1 is the first brand named. You may scope the chart to a single brand by passing brand_id, or to every brand in a segment by passing segments. Otherwise, the result is capped to the top top_n brands by mention count. A per-bucket value is null when the brand had no mentions in that bucket.

GET /api/v1/analytics/position-time-series

Query parameters

Name	Type	Required	Description
start_date	string	Required	The inclusive UTC start of the analytics window, given as an ISO 8601 date (`YYYY-MM-DD`).
end_date	string	Required	The inclusive UTC end of the analytics window. The value must be on or after `start_date`, and on or before today.
interval	string	Required	The bucketing granularity for time-series endpoints. Accepted values: `day`, `week`, `month`, and `year`. Week buckets begin on Monday.
brand_id	integer	Optional	You may set this parameter to scope a time-series chart to a single brand, which produces a single-brand line. The brand must belong to the active project. A single-brand share-of-voice series is measured against the brand's own mentions, so it reads `100` in any bucket where the brand has mentions.
platforms	string[]	Optional	You may use this parameter to limit responses to one or more AI platforms. Repeat the parameter for each value, for example `?platforms[]=chatgpt&platforms[]=claude`. When omitted, every platform is included. Accepted values: `chatgpt`, `perplexity`, `gemini`, `grok`, `copilot`, `claude`, `google_ai_mode`, and `google_ai_overview`.
countries	string[]	Optional	You may use this parameter to limit responses to monitors run in the given ISO-3166-1 alpha-2 country codes.
monitors	integer[]	Optional	You may use this parameter to limit responses to specific monitors inside the active project.
segments	integer[]	Optional	You may use this parameter to limit responses and brand-scoped metrics to brands attached to any of the given segments. Segments are named groupings of brands, such as `Direct Competitors`. When this parameter is set, time-series charts show every brand in the selected segments instead of capping the series at `top_n`, and share-of-voice ratios are computed within the segment, so each brand's share reads against the other brands in the selected segments. Source-keyed endpoints do not honor this parameter.
tags	integer[]	Optional	You may use this parameter to limit responses to those whose prompt carries any of the given tag IDs, such as `branded` or `non-branded`.
top_n	integer	Optional	The maximum number of series to return from a time-series endpoint. Series are ranked by total mentions or citations in the window. Defaults to 20, with a maximum of 50.

Response

Position time-series

Field	Type	Description
interval	string
series	BrandPositionSeries[]	One entry per brand in scope, each carrying a dense list of buckets.

Per-brand position series

Field	Type	Description
brand	Brand	The brand this series covers.
data	PositionTimeSeriesPoint[]	The bucketed data points for this brand.

Position time-series data point

Field	Type	Description
timestamp	datetime	The ISO 8601 UTC start of the bucket.
value	number	The average position of the brand's mentions in the bucket, where a lower number is a more prominent placement and `1` is the first brand named. `null` when the brand was not mentioned in this bucket.