---
title: "Get the usage breakdown"
method: GET
path: "/v1/usage/breakdown"
tags: ["Usage"]
---

# Get the usage breakdown

`GET /v1/usage/breakdown`

## Request

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

What the workspace consumed and was charged over a window, grouped by one dimension per call (`by`: day, platform or keyword), in USD cents at list price, with the window's totals on every call. `range` reads a trailing window of UTC days ending today (default 30d); `month` reads one calendar month (YYYY-MM), the shape a bill or a per-customer margin is reconciled against. Keyword-days come from the daily tick and mention charges from the matches that billed, so a deleted keyword keeps its charges in the keyword rows (`keyword.removed`) while its mention counts read 0; the same numbers ride on each keyword as `stats.cost` for the running month. `totals.ledgerDebitCents` is what the wallet has debited so far for the window's days: mentions settle the morning after their day, so a window ending today lags `totals.totalCents` by the unsettled ones, and a closed month differs from it only by cumulative rounding. Rows are paged (`limit`, `offset`, `total`); a workspace may read this at most 30 times a minute through its keys and tokens together.

## Query parameters

- `by` 'day' | 'platform' | 'keyword' | 'group': The dimension to group by: day (one row per UTC day of the window), platform, keyword (default: the row a margin is computed from), or group (what a customer or a campaign cost).
- `range` '7d' | '30d' | '90d': Trailing window of UTC days ending today: 7d, 30d, 90d (default 30d). Ignored when `month` is given.
- `month` string: A calendar month (YYYY-MM, UTC) instead of a trailing window: from its first day to its last, or to today for the running month. A future month is a 400.
- `from` string: First UTC day of a custom window, YYYY-MM-DD, inclusive; with `to` (default today). At most 366 days. Wins over `range` and `month`.
- `to` string: Last UTC day of a custom window, YYYY-MM-DD, inclusive; never after today. Needs `from`.
- `keywordIds` string[], nullable: Only these keywords (kw_...), deleted ones included. Repeatable, or comma-separated.
- `groupIds` string[], nullable: Only these groups (grp_...): a keyword-day by the group it was metered under, a mention or a comment by its keyword's group as it is now. Repeatable, or comma-separated.
- `platforms` string[]: Only these platforms. A keyword-day belongs to no platform, so with this filter the keyword line reads 0 and only mentions and comments count. Repeatable, or comma-separated.
- `limit` integer: Rows per page, 1 to 500 (default 100). Only by=keyword can outgrow a page; a window has at most 90 days and a dozen platforms.
- `offset` integer, nullable: Skip this many rows.

## Response `200`

The window's totals and one page of rows for the dimension

- UsageBreakdown
  - `window` object, required: The window the report covers, in UTC days.
    - `from` string, required: First day, YYYY-MM-DD, inclusive, UTC.
    - `to` string, required: Last day, inclusive: today for a trailing window or the running month.
    - `days` integer, required: Length of the window in days.
    - `keywordDaysFrom` string, nullable, required: The first day of the window with a recorded keyword count, or null when there is none. Earlier days carry keywordDays: null.
  - `by` 'day' | 'platform' | 'keyword' | 'group', required: The dimension the rows are grouped by.
  - `filtered` boolean, required: true when keywordIds, groupIds or platforms narrowed the report: totals and rows count only what passes them, except totals.ledgerDebitCents, which is the whole workspace's.
  - `currency` 'USD', required: Every amount is in USD cents.
  - `totals` object, required: The whole window as one line, the same for every dimension.
    - `keywordDays` integer, required: Keyword-days metered in the window.
    - `keywordCents` integer, required: The keyword-days at the keyword rate ($5 a month, 500/30 cents a day), rounded once on the total.
    - `matchedMentions` integer, required: Matches recorded in the window, relevant or not.
    - `billableMentions` integer, required: Of the matches billed in the window (every scored match, relevant or not), the ones in this group.
    - `unclassifiedMentions` integer, required: Matches recorded in the window that are never charged: no score yet (still being scored, or classification failed), or a free review from the look-back of a newly connected app. Every other match is charged, on the mentions line or, for a comment, on the comments line.
    - `mentionCents` integer, required: The billed mentions at $0.008 each, rounded once on the total.
    - `billableComments` integer, required: Comments billed in the window (the comments line): comments delivered under your mentions and comments that matched a keyword, each once per workspace.
    - `commentCents` integer, required: The billed comments at $0.008 each, rounded once on the total.
    - `totalCents` integer, required: keywordCents plus mentionCents plus commentCents.
    - `ledgerDebitCents` integer, required: What the ledger has debited so far for the days of the window, each debit by the day it settled, for the whole workspace whatever the filters. Mentions settle the morning after their day, so a window ending today lags totalCents by today's mentions (and yesterday's before the tick at 00:05 UTC); a closed month differs from totalCents only by cumulative rounding.
    - `unattributedBillable` integer, required: Billed mentions whose match row is gone (deleted keyword), so no platform or keyword row can claim them. Charged all the same. Comments carry their keyword and platform on the billed row, so they are never unattributed (by=group puts a deleted keyword's comments on the no-group row).
  - `data` object[], required: by=day: chronological. by=platform and by=keyword: most expensive first, then most matched, deleted keywords included.
    - `key` string, required: The row's key: the UTC day (YYYY-MM-DD) for by=day, the platform for by=platform, the keyword id for by=keyword, the group id for by=group.
    - `label` string, required: Readable name: the keyword term or the group name, otherwise the key.
    - `keyword` object, nullable, required: by=keyword only; null otherwise.
      - `id` string, required: Keyword id (kw_...); a deleted keyword keeps its id here.
      - `term` string, required: The term as it was last metered, or as the keyword reads now.
      - `removed` boolean, required: The keyword has since been deleted. Its charges stay on the record; its mentions went with it, so its mention counts read 0.
    - `group` object, nullable, required: by=group only; null otherwise.
      - `id` string, required: Group id, or "none" for keyword-days metered before groups existed whose keyword is gone.
      - `name` string, required: The group's name as it reads now, or "Deleted group" / "No group".
      - `removed` boolean, required: The group has since been deleted.
    - `keywordDays` integer, nullable, required: Keyword-days metered in this group: the days the daily tick charged for. Null for by=platform (a keyword-day belongs to no platform) and for a day before the first recorded tick (unknown, not zero); a keyword row counts only the days on record, so before window.keywordDaysFrom it is a floor, not a zero.
    - `keywordCents` integer, required: The keyword-days at the keyword rate ($5 a month, 500/30 cents a day), rounded once on the total.
    - `matchedMentions` integer, required: Matches recorded in the window, relevant or not.
    - `billableMentions` integer, required: Of the matches billed in the window (every scored match, relevant or not), the ones in this group.
    - `unclassifiedMentions` integer, required: Matches recorded in the window that are never charged: no score yet (still being scored, or classification failed), or a free review from the look-back of a newly connected app. Every other match is charged, on the mentions line or, for a comment, on the comments line.
    - `mentionCents` integer, required: The billed mentions at $0.008 each, rounded once on the total.
    - `billableComments` integer, required: Comments billed in the window (the comments line): comments delivered under your mentions and comments that matched a keyword, each once per workspace.
    - `commentCents` integer, required: The billed comments at $0.008 each, rounded once on the total.
    - `totalCents` integer, required: keywordCents plus mentionCents plus commentCents.
  - `total` integer, required: Rows in the dimension before `limit` and `offset`.

## Other responses

- `400`: Unknown dimension or range, month malformed or in the future, limit out of range
- `401`: Missing or invalid API key
- `429`: More than 30 breakdown reads this minute for the workspace

---

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