---
title: "Mentions over time"
method: GET
path: "/v1/analytics/series"
tags: ["Analytics"]
---

# Mentions over time

`GET /v1/analytics/series`

## Request

- Base URL: `https://api.rumoro.dev`
- URL: `https://api.rumoro.dev/v1/analytics/series`
- Auth: HTTP bearer

Returns matched, relevant and sentiment counts per day or week over the period. You get one total series, or one per platform or keyword with `by`. Pick the period with `range` (7d, 30d, 90d or 365d up to today) or with `from` and `to`. Days follow `timezone`, UTC by default. `keywordIds` and `platforms` narrow the data, and `compare=true` adds the equally long period just before. Dates are publish dates.

## Query parameters

- `range` '7d' | '30d' | '90d' | '365d': A preset period up to today, 30d by default. Ignored when you send from or to.
- `from` string: Start date in `timezone`, as YYYY-MM-DD. That day is included.
- `to` string: End date in `timezone`, as YYYY-MM-DD, included. Defaults to today.
- `keywordIds` string[], nullable: Keeps these keyword ids only. Repeat the parameter or separate values with commas. Leave it out for all keywords.
- `platforms` string[]: Keeps these platforms only. Repeat the parameter or separate values with commas. Leave it out for all platforms.
- `compare` boolean: true adds the equally long period just before as `previous`.
- `timezone` string: The IANA time zone used to split days, such as America/New_York. Defaults to UTC. The zone's offset at the end of the period is used for the whole period.
- `bucket` 'hour' | 'day' | 'week' | 'month': The size of each point. hour for periods up to 14 days, day, week (starting Monday) or month. By default days up to 90 days and weeks beyond.
- `by` 'platform' | 'keyword' | 'sentiment': Splits the data into a series for each platform, each keyword or each sentiment (positive, neutral, negative, unclassified). By keyword you get the top 20 by matches, with the rest combined as "other". Leave it out for one total series.

## Response `200`

The series with zeros for empty points, oldest first

- AnalyticsSeries
  - `window` object, required: Start and end of the period.
    - `from` string, required: The first day included.
    - `to` string, required: The last day included.
    - `days` integer, required: How many days the window spans.
    - `timezone` string, required: The IANA time zone used to split the days.
    - `bucket` 'hour' | 'day' | 'week' | 'month', required: The size of each point. One of hour, day, week (Monday to Sunday) or month.
  - `data` object[], required: One item for each series, the one with the most matches first. Without a split there is a single "total" item.
    - `key` string, required: A platform name, a keyword id or a sentiment (positive, neutral, negative, unclassified). It is "total" when the series is not split and "other" for everything past the top 20.
    - `label` string, required: Display name such as a platform, keyword term or sentiment, or "Total" and "Other".
    - `keyword` object, nullable, required: The keyword, when split by keyword. Otherwise null.
      - `id` string, required: The keyword's id (kw_...).
      - `term` string, required: The term being tracked.
      - `kind` 'brand' | 'competitor' | 'topic', required: The keyword's kind, brand, competitor or topic.
      - `group` object, required: The keyword's group.
        - `id` string, required: The group's id (grp_...).
        - `name` string, required: Name of the group.
        - `externalId` string, nullable, required: An id from your own system, or null.
        - `isDefault` boolean, required: True for the workspace's default group. New keywords go there when you don't name a group.
    - `points` object[], required: A point for every step of the window, oldest first, with zeros where nothing matched.
      - `date` string, required: Start of the point in `timezone`. YYYY-MM-DD for a day, the Monday for a week, the 1st for a month, or YYYY-MM-DDTHH:00 for an hour.
      - `matched` integer, required: All matches published during this point.
      - `relevant` integer, required: How many of them scored 40 or more.
      - `positive` integer, required: Matches with positive sentiment.
      - `neutral` integer, required: Matches with neutral sentiment.
      - `negative` integer, required: Matches with negative sentiment.
      - `unclassified` integer, required: Matches without a score, either still waiting or failed.
  - `previous` object[], nullable, required: With compare=true, the same items for the prior period in the same order, index-aligned with `data`. The last point can be missing when weeks split differently. Otherwise null.
    - `key` string, required: A platform name, a keyword id or a sentiment (positive, neutral, negative, unclassified). It is "total" when the series is not split and "other" for everything past the top 20.
    - `label` string, required: Display name such as a platform, keyword term or sentiment, or "Total" and "Other".
    - `keyword` object, nullable, required: The keyword, when split by keyword. Otherwise null.
      - `id` string, required: The keyword's id (kw_...).
      - `term` string, required: The term being tracked.
      - `kind` 'brand' | 'competitor' | 'topic', required: The keyword's kind, brand, competitor or topic.
      - `group` object, required: The keyword's group.
        - `id` string, required: The group's id (grp_...).
        - `name` string, required: Name of the group.
        - `externalId` string, nullable, required: An id from your own system, or null.
        - `isDefault` boolean, required: True for the workspace's default group. New keywords go there when you don't name a group.
    - `points` object[], required: A point for every step of the window, oldest first, with zeros where nothing matched.
      - `date` string, required: Start of the point in `timezone`. YYYY-MM-DD for a day, the Monday for a week, the 1st for a month, or YYYY-MM-DDTHH:00 for an hour.
      - `matched` integer, required: All matches published during this point.
      - `relevant` integer, required: How many of them scored 40 or more.
      - `positive` integer, required: Matches with positive sentiment.
      - `neutral` integer, required: Matches with neutral sentiment.
      - `negative` integer, required: Matches with negative sentiment.
      - `unclassified` integer, required: Matches without a score, either still waiting or failed.

## Other responses

- `400`: The query is not valid
- `401`: The API key is missing or not valid

---

[API](https://skmtc.dev/rumoro/apis/rumoro-api.md) · [All operations](https://skmtc.dev/rumoro/apis/rumoro-api/llms.txt) · [OpenAPI document](https://skmtc.dev/rumoro/apis/rumoro-api/revisions/9ef63ea894d1?raw)