---
title: "Get the usage breakdown"
description: "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."
canonical: https://docs.rumoro.dev/api/usage/get-usage-breakdown
markdown: https://docs.rumoro.dev/api/usage/get-usage-breakdown.mdx
---

# Get the usage breakdown

`GET /v1/usage/breakdown`

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.

## Parameters

| Name | In | Description |
| --- | --- | --- |
| `by` | query | 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` | query | How many UTC days back from today to read. One of 7d, 30d or 90d, 30d by default. Ignored when you send `month`. |
| `month` | query | 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` | query | 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` | query | How many rows to skip. |

## Responses

| Status | Meaning |
| --- | --- |
| 200 | The period's totals and a page of rows |
| 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 |

The [OpenAPI document](https://api.rumoro.dev/v1/openapi.json) has every schema. Rules shared by all endpoints are in [Conventions](https://docs.rumoro.dev/conventions.mdx).