---
title: "Mentions grouped by one dimension"
method: GET
path: "/v1/analytics/breakdown"
tags: ["Analytics"]
---

# Mentions grouped by one dimension

`GET /v1/analytics/breakdown`

## Request

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

One table of matched, relevant and sentiment counts grouped by `by`: platform, keyword, sentiment, intent, status, hour (weekday and hour of day) or person. 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.
- `by` 'platform' | 'keyword' | 'sentiment' | 'intent' | 'status' | 'hour' | 'person' | 'language' | 'country' | 'subreddit', required: The dimension to group by: platform, keyword, sentiment (unclassified included), intent (a mention can carry several), status (open, ignored, done), hour (weekday and hour of day in `timezone`), person (who posted; anonymous posts are left out), language (ISO 639-1; "unknown" for posts without one), country (where the author is, ISO 3166-1 alpha-2; "unknown" for posts without one), subreddit (Reddit posts only, most active first; `share` stays a percent of the whole window, every platform included).

## Response `200`

Groups, most matched first

- AnalyticsBreakdown
  - `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.
  - `by` 'platform' | 'keyword' | 'sentiment' | 'intent' | 'status' | 'hour' | 'person' | 'language' | 'country' | 'subreddit', required: The dimension the rows are grouped by.
  - `data` object[], required: Most matched first, at most 50 groups. by=hour is chronological and unlimited (168 cells at most).
    - `key` string, required: The group: platform name, keyword id, sentiment, intent, status, "weekday-hour" for by=hour, an opaque person key, or the subreddit in lowercase.
    - `label` string, required: Readable name: the keyword term, the person name, the subreddit as Reddit spells it, otherwise the key.
    - `keyword` object, nullable, required: by=keyword only; 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.
    - `person` object, nullable, required: by=person only; null otherwise.
      - `id` string, nullable, required: Person id (aut_...); null for posts ingested before people were linked.
      - `name` string, nullable, required: Display name as the platform shows it.
      - `platform` 'bluesky' | 'hackernews' | 'github' | 'stackoverflow' | 'devto' | 'reddit' | 'x' | 'youtube' | 'news' | 'linkedin' | 'tiktok' | 'instagram' | 'appstore' | 'googleplay' | 'trustpilot' | 'googlemaps' | 'rss', required: Platform: bluesky, hackernews, github, stackoverflow, devto, reddit, x, youtube, news, linkedin, tiktok, instagram, appstore (App Store reviews), googleplay (Google Play reviews), trustpilot (Trustpilot reviews), googlemaps (Google reviews of a place), rss (RSS and Atom feeds a keyword reads).
      - `url` string, nullable, required: Profile URL.
      - `avatarUrl` string, nullable, required: Avatar image URL, when the platform gave one.
      - `followers` integer, nullable, required: From the audience profile; null when unknown.
    - `slot` object, nullable, required: by=hour only: the weekday and hour of day in `timezone`; null otherwise.
      - `weekday` integer, required: 0 = Sunday through 6 = Saturday.
      - `hour` integer, required: Hour of day, 0 to 23.
    - `matched` integer, required: Matches in the group.
    - `relevant` integer, required: Of those, scored at or above the relevance threshold.
    - `share` number, required: Percent of the window's matched mentions in this group, one decimal. Intents overlap, so their shares can add up past 100.
    - `sentiment` object, required: Matched mentions by classifier sentiment.
      - `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 group over the period right before the window; null unless compare=true.
      - `matched` integer, required: Matches in the group then.
      - `relevant` integer, required: Relevant matches in the group then.

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