---
title: "Get a mention breakdown"
method: GET
path: "/v1/analytics/breakdown"
tags: ["Analytics"]
---

# Get a mention breakdown

`GET /v1/analytics/breakdown`

## Request

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

`by` sets the rows (platform, keyword, sentiment, intent, status, hour as weekday and hour, or person), and each row has matched, relevant and sentiment counts. 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.
- `by` 'platform' | 'keyword' | 'sentiment' | 'intent' | 'status' | 'hour' | 'person' | 'language', required: How to group the rows. platform, keyword, sentiment (unclassified included), intent (a mention can have several), status (open, ignored, done), hour (weekday and hour in `timezone`), person (the author, without anonymous posts) or language (ISO 639-1, or "unknown" when there is none).

## Response `200`

The rows, the one with the most matches first

- AnalyticsBreakdown
  - `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.
  - `by` 'platform' | 'keyword' | 'sentiment' | 'intent' | 'status' | 'hour' | 'person' | 'language', required: Grouping used for the rows.
  - `data` object[], required: Up to 50 rows, the one with the most matches first. With by=hour the rows are in time order and not limited, so up to 168.
    - `key` string, required: What the row stands for. A platform name, keyword id, sentiment, intent or status, "weekday-hour" with by=hour, or a person key you should not parse.
    - `label` string, required: A name to display. The keyword's term or the person's name, or else the key.
    - `keyword` object, nullable, required: Set only with by=keyword. Null otherwise.
      - `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.
    - `person` object, nullable, required: Set only with by=person. Null otherwise.
      - `id` string, nullable, required: The person's aut_... id. Older posts, from before people were linked, have null.
      - `name` string, nullable, required: The name shown on the platform.
      - `platform` 'bluesky' | 'hackernews' | 'github' | 'stackoverflow' | 'devto' | 'reddit' | 'x' | 'youtube' | 'news' | 'linkedin' | 'tiktok' | 'instagram' | 'appstore' | 'googleplay' | 'trustpilot' | 'googlemaps' | 'rss', required: The platform. Review platforms are appstore, googleplay, trustpilot and googlemaps (a place's Google reviews).
      - `url` string, nullable, required: Link to the profile.
      - `avatarUrl` string, nullable, required: Link to the profile picture, if the platform provided one.
      - `followers` integer, nullable, required: Follower count from the audience profile, or null.
    - `slot` object, nullable, required: Weekday and hour in `timezone` when by=hour, otherwise null.
      - `weekday` integer, required: The day of the week, from 0 for Sunday to 6 for Saturday.
      - `hour` integer, required: The hour, from 0 to 23.
    - `matched` integer, required: Matches in this row.
    - `relevant` integer, required: How many of them scored 40 or more.
    - `share` number, required: The percentage of the window's matches that fall in this row, with one decimal. A mention can have several intents, so intent shares can total more than 100.
    - `sentiment` object, required: Sentiment split of the matched mentions.
      - `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: This row for the period just before the window. Null unless compare=true.
      - `matched` integer, required: Matches in this row during that period.
      - `relevant` integer, required: Relevant matches in this row during that period.

## 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)