---
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.rumoro.dev`
- URL: `https://api.rumoro.dev/v1/usage/breakdown`
- Auth: HTTP bearer

Returns what the workspace used and was charged over a period, in US cents at list price. Each call groups rows by one `by` value, day, platform or keyword, and always includes the totals. `range` reads the past UTC days up to today (30d by default). `month` reads one calendar month (YYYY-MM), which is what you match against a bill or a per-client margin. Keyword-days come from the daily run and mention charges from billed matches. So a deleted keyword keeps its charges in the keyword rows (`keyword.removed`), while its mention counts show 0. Each keyword carries the same numbers for the current month as `stats.cost`. `totals.ledgerDebitCents` is what the balance has been debited so far for the period's days. Mentions settle the morning after, so a period ending today is below `totals.totalCents` by the unsettled ones, and a finished month differs only by cumulative rounding. Rows come in pages (`limit`, `offset`, `total`). A workspace can call this 30 times a minute across all its keys and tokens.

## Query parameters

- `by` 'day' | 'platform' | 'keyword' | 'group': How to group the rows. day gives one row per UTC day, then platform, keyword (the default, used to work out margins), or group (the cost of a client or campaign).
- `range` '7d' | '30d' | '90d': How many UTC days back from today to read. One of 7d, 30d or 90d, 30d by default. Ignored when you send `month`.
- `month` string: A calendar month (YYYY-MM, UTC) to read instead of a range. It covers the month's first to last day, or up to today for the current month. A future month returns 400.
- `limit` integer: How many rows to return, from 1 to 500, 100 by default. Only by=keyword can need more than one page, since a period has at most 90 days and there are only a dozen platforms.
- `offset` integer, nullable: How many rows to skip.

## Response `200`

The period's totals and a page of rows

- UsageBreakdown
  - `window` object, required: Report range in UTC days.
    - `from` string, required: Start date (UTC, YYYY-MM-DD), included.
    - `to` string, required: The last day included. It is today for a trailing range or the current month.
    - `days` integer, required: How many days the window spans.
    - `keywordDaysFrom` string, nullable, required: Earliest day in the window with a keyword count, or null. Earlier days show `keywordDays: null`.
  - `by` 'day' | 'platform' | 'keyword' | 'group', required: Grouping used for the rows.
  - `currency` 'USD', required: All amounts are in US cents.
  - `totals` object, required: Totals for the whole window. They are the same whatever `by` is.
    - `keywordDays` integer, required: Sum of keyword-days over the window.
    - `keywordCents` integer, required: Those keyword-days priced at $5 a month (500/30 cents a day), with the total rounded once.
    - `matchedMentions` integer, required: Match count for the window, relevant or not.
    - `billableMentions` integer, required: Matches billed in the window that fall in this row. Every scored match is billed, relevant or not.
    - `mentionCents` integer, required: Those mentions priced at $0.008 each, with the total rounded once.
    - `billableComments` integer, required: Comments billed on the comments line: comments delivered under mentions and matched replies, each once per workspace.
    - `commentCents` integer, required: Those comments at $0.008 each, rounded once on the total.
    - `totalCents` integer, required: keywordCents plus mentionCents plus commentCents.
    - `unclassifiedMentions` integer, required: Matches whose classification failed. They are never charged.
    - `ledgerDebitCents` integer, required: Debits recorded so far for the window's days, each on its settlement day. Mentions settle the next morning, so a window ending today trails totalCents by today's mentions, plus yesterday's before the 00:05 UTC run. A closed month differs only by cumulative rounding.
    - `unattributedBillable` integer, required: Billed mentions whose match was removed with a deleted keyword, so they belong to no platform or keyword row. They were still charged.
  - `data` object[], required: With by=day the rows are in date order. With by=platform and by=keyword the most expensive come first, then those with the most matches, deleted keywords included.
    - `key` string, required: What the row stands for. A UTC day (YYYY-MM-DD) with by=day, a platform with by=platform, a keyword id with by=keyword and a group id with by=group.
    - `label` string, required: A name to display. The keyword's term or the group'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_...). Deleted keywords keep their id here.
      - `term` string, required: The term when it was last charged, or its current term.
      - `removed` boolean, required: The keyword was deleted later. Charges remain, but its mentions are gone, so mention counts are 0.
    - `group` object, nullable, required: Set only with by=group. Null otherwise.
      - `id` string, required: The group's id. It is "none" for keyword-days charged before groups existed when the keyword has since been deleted.
      - `name` string, required: Current group name, or "Deleted group" or "No group".
      - `removed` boolean, required: True when the group was deleted later.
    - `keywordDays` integer, nullable, required: Keyword-days charged in this row by the daily run. Null with by=platform, since a keyword-day has no platform, and for days before the first recorded run, where the count is unknown rather than zero. A keyword row only counts recorded days, so before window.keywordDaysFrom it is a minimum, not zero.
    - `keywordCents` integer, required: Those keyword-days priced at $5 a month (500/30 cents a day), with the total rounded once.
    - `matchedMentions` integer, required: Match count for the window, relevant or not.
    - `billableMentions` integer, required: Matches billed in the window that fall in this row. Every scored match is billed, relevant or not.
    - `mentionCents` integer, required: Those mentions priced at $0.008 each, with the total rounded once.
    - `billableComments` integer, required: Comments billed on the comments line: comments delivered under mentions and matched replies, each once per workspace.
    - `commentCents` integer, required: Those comments at $0.008 each, rounded once on the total.
    - `totalCents` integer, required: keywordCents plus mentionCents plus commentCents.
  - `total` integer, required: The number of rows before `limit` and `offset` are applied.

## Other responses

- `400`: Invalid by, range, month or limit. A future month is invalid too
- `401`: The API key is missing or not valid
- `429`: The workspace read the breakdown over 30 times in this minute

---

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