# 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`](https://docs.maitento.com/reference/types/usage-totals.md) | The totals for the whole filtered range. |
| `rows` | [`UsageBreakdownRow`](https://docs.maitento.com/reference/types/usage-breakdown-row.md)`[]` | The largest groups by `sort`, descending (then by key). |
| `other` | [`UsageTotals`](https://docs.maitento.com/reference/types/usage-totals.md)`\| null` | The groups past the limit, summed; null when there are none. |
| `otherCount` | `integer` | How many groups are summed into `other`. |

## Example

```json
{
  "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`](https://docs.maitento.com/reference/api/usage.md) (`GET /usage/breakdown`)