--- title: "Mentions over time" method: GET path: "/v1/analytics/series" tags: ["Analytics"] --- # Mentions over time `GET /v1/analytics/series` ## Request - Base URL: `https://api.mentio.dev` - URL: `https://api.mentio.dev/v1/analytics/series` - Auth: HTTP bearer Matched, relevant and sentiment counts per day or week across the window, as one total series or split per platform or per keyword with `by`. The window is `range` (7d, 30d, 90d, 365d, ending today) or `from` and `to`, cut into days in `timezone` (UTC by default); `keywordIds` and `platforms` narrow it; `compare=true` adds the period of the same length right before it. Time axis is the publish date. ## Query parameters - `range` '7d' | '30d' | '90d' | '365d': Preset window ending today. Ignored when from or to is given. Default 30d. - `from` string: First day, YYYY-MM-DD, inclusive, in `timezone`. - `to` string: Last day, YYYY-MM-DD, inclusive, in `timezone`. Default today. - `keywordIds` string[], nullable: Only these keyword ids. Repeatable, or comma-separated; omit for every keyword. - `platforms` string[]: Only these platforms. Repeatable, or comma-separated; omit for every platform. - `compare` boolean: true adds the period of the same length right before the window as `previous`. - `timezone` string: IANA zone the days are cut in (Europe/Madrid). Default UTC. One offset, the zone's at the end of the window, applies to the whole window. - `bucket` 'hour' | 'day' | 'week' | 'month': Point granularity: hour (windows of at most 14 days), day, week (Monday start) or month. Default: day up to 90 days, week beyond. - `by` 'platform' | 'keyword' | 'sentiment': Split into one series per platform, per keyword (the top 20 by matched, the rest folded into "other") or per sentiment (positive, neutral, negative, unclassified). Omit for one total series. ## Response `200` Zero-filled series, oldest point first - AnalyticsSeries - `window` object, required: The window the report covers. - `from` string, required: First day, inclusive. - `to` string, required: Last day, inclusive. - `days` integer, required: Length of the window in days. - `timezone` string, required: IANA zone the days were cut in. - `bucket` 'hour' | 'day' | 'week' | 'month', required: Point granularity used: hour, day, week (Monday to Sunday) or month. - `data` object[], required: One item per series, most matched first; a single "total" item when not split. - `key` string, required: Platform name, keyword id, sentiment (positive, neutral, negative, unclassified), "total" for the unsplit series, or "other" for the keys beyond the top 20. - `label` string, required: Readable name: the platform, the keyword term, the sentiment, "Total" or "Other". - `keyword` object, nullable, required: Set when split by keyword; null otherwise. - `id` string, required: Keyword id (kw_...). - `term` string, required: The tracked term. - `kind` 'brand' | 'competitor' | 'topic', required: brand, competitor or topic. - `group` object, required: The group the keyword is in. - `id` string, required: Group id (grp_...). - `name` string, required: The group's name. - `externalId` string, nullable, required: Your own id for the group, or null. - `isDefault` boolean, required: The workspace's default group, where a keyword lands when no group is named. - `points` object[], required: One point per bucket across the window, oldest first, zero-filled. - `date` string, required: The bucket start in `timezone`: the day (YYYY-MM-DD), the Monday of the week, the first of the month, or the hour as YYYY-MM-DDTHH:00. - `matched` integer, required: Every match published in the bucket. - `relevant` integer, required: Of those, scored at or above the relevance threshold. - `positive` integer, required: Classified positive. - `neutral` integer, required: Classified neutral. - `negative` integer, required: Classified negative. - `unclassified` integer, required: Not scored: still queued, or the classifier failed on it. - `previous` object[], nullable, required: The same items over the period right before the window, in the same order, points aligned by index with `data` (the last bucket may be missing when weeks split differently); null unless compare=true. - `key` string, required: Platform name, keyword id, sentiment (positive, neutral, negative, unclassified), "total" for the unsplit series, or "other" for the keys beyond the top 20. - `label` string, required: Readable name: the platform, the keyword term, the sentiment, "Total" or "Other". - `keyword` object, nullable, required: Set when split by keyword; null otherwise. - `id` string, required: Keyword id (kw_...). - `term` string, required: The tracked term. - `kind` 'brand' | 'competitor' | 'topic', required: brand, competitor or topic. - `group` object, required: The group the keyword is in. - `id` string, required: Group id (grp_...). - `name` string, required: The group's name. - `externalId` string, nullable, required: Your own id for the group, or null. - `isDefault` boolean, required: The workspace's default group, where a keyword lands when no group is named. - `points` object[], required: One point per bucket across the window, oldest first, zero-filled. - `date` string, required: The bucket start in `timezone`: the day (YYYY-MM-DD), the Monday of the week, the first of the month, or the hour as YYYY-MM-DDTHH:00. - `matched` integer, required: Every match published in the bucket. - `relevant` integer, required: Of those, scored at or above the relevance threshold. - `positive` integer, required: Classified positive. - `neutral` integer, required: Classified neutral. - `negative` integer, required: Classified negative. - `unclassified` integer, required: Not scored: still queued, or the classifier failed on it. ## Other responses - `400`: Invalid query - `401`: Missing or invalid API key --- [API](https://skmtc.dev/mentio/apis/mentio-api.md) · [All operations](https://skmtc.dev/mentio/apis/mentio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mentio/apis/mentio-api/revisions/b16a21d0ed02?raw)