UsageBreakdown

A range’s usage grouped by one dimension, such as by namespace or by model. Drill in by filtering on a row’s key.

Kind: an object, used in responses.

Fields

Every field is present in a response; empty ones are null.

Field	Type	Description
from	datetime	The start of the range, in UTC.
to	datetime	The end of the range, in UTC.
groupBy	string	The dimension the usage is grouped by.
sort	string	The measure the rows are ordered by.
total	UsageTotals	The totals for the whole filtered range.
rows	UsageBreakdownRow[]	The largest groups by sort, descending (then by key).
other	UsageTotals| null	The groups past the limit, summed; null when there are none.
otherCount	integer	How many groups are summed into other.

Example

{
  "from": "2026-10-26T12:00:00.0000000Z",
  "to": "2026-10-26T12:00:00.0000000Z",
  "groupBy": "...",
  "sort": "...",
  "total": {
    "runs": 0,
    "runtimeMs": 0,
    "executionMs": 0,
    "steps": 0,
    "stepRuntimeMs": 0,
    "toolCalls": 0,
    "tokens": {
      "input": 0,
      "output": 0,
      "cacheRead": 0,
      "cacheWrite": 0,
      "reasoning": 0,
      "total": 0
    },
    "webSearches": 0,
    "webPages": 0,
    "webDownloads": 0,
    "imageDescriptions": 0,
    "webCredits": 0,
    "webBytes": 0
  },
  "rows": [
    {
      "key": "...",
      "label": "...",
      "detail": "...",
      "totals": {}
    }
  ],
  "other": {
    "runs": 0,
    "runtimeMs": 0,
    "executionMs": 0,
    "steps": 0,
    "stepRuntimeMs": 0,
    "toolCalls": 0,
    "tokens": {
      "input": 0,
      "output": 0,
      "cacheRead": 0,
      "cacheWrite": 0,
      "reasoning": 0,
      "total": 0
    },
    "webSearches": 0,
    "webPages": 0,
    "webDownloads": 0,
    "imageDescriptions": 0,
    "webCredits": 0,
    "webBytes": 0
  },
  "otherCount": 0
}

Where it’s used

• usage.breakdown (GET /usage/breakdown)