# UsageBreakdownRequest

What to group a usage breakdown by, how to order it, and the usual usage filters.

**Kind:** an object, used in requests.

## Fields

| Field | Type | Required | Description |
|---|---|---|---|
| `groupBy` | `string \| null` |  | Required: the dimension to group by: `namespace`, `type`, `definition`, `version`, `agent`, `provider`, `model`, `engine`, `credentialKind`, `tier`, `outcome`, `startedBy`, `trigger` or `root`. |
| `sort` | `string \| null` |  | The measure to order rows by, descending: any `metric` a series takes (default `tokens`). |
| `limit` | `integer \| null` |  | How many rows: 1 to 500 (clamped), default 50. The rest are summed into `other`. |
| `from` | `string \| null` |  | The start of the range: ISO 8601 with an offset, rounded down to the hour (UTC). Default: `to` minus 7 days. |
| `to` | `string \| null` |  | The end of the range: ISO 8601 with an offset, rounded up to the hour (UTC). Default: the start of the next hour. |
| `namespace` | `string[] \| null` |  | Namespace names, matched as `GET /processes` matches them. The name a deleted or renamed namespace had also matches. |
| `type` | `string[] \| null` |  | Kinds of run: `Interaction`, `App`, `Capsule` or `CodePipeline` (case-insensitive). |
| `definitionId` | `string[] \| null` |  | Ids of the definitions (interactions, apps, capsules, code pipelines) whose runs to include. |
| `version` | `string[] \| null` |  | Definition versions, as `{definitionId}:{version}`. |
| `agent` | `string[] \| null` |  | Agent names: the interaction or code pipeline agents whose turns or steps used the tokens. |
| `provider` | `string[] \| null` |  | The AI providers that served interaction turns, such as `Anthropic`. |
| `model` | `string[] \| null` |  | Model names. |
| `engine` | `string[] \| null` |  | Code pipeline engines, as `CodeEngineType` names. |
| `credentialKind` | `string[] \| null` |  | Whose provider key served the tokens: `Own` (the tenant's or the run's own key), `Platform` (Maitento's) or `Unknown` (none was recorded). |
| `tier` | `string[] \| null` |  | Pricing tiers, for models whose price depends on how many tokens a request uses. |
| `outcome` | `string[] \| null` |  | How the runs ended: `InProgress`, `Finished`, `Error` or `Killed`. |
| `startedBy` | `string[] \| null` |  | What started the runs: `User`, `Automation` or `Parent`. |
| `triggerId` | `string[] \| null` |  | Ids of the users or automations that started the runs. |
| `rootDefinitionId` | `string[] \| null` |  | Definition ids of the runs at the top of the tree: everything an app (or any top-level run) caused, the runs it started included. |

## Example

```json
{
  "groupBy": "...",
  "sort": "...",
  "limit": 0,
  "from": "...",
  "to": "...",
  "namespace": [
    "..."
  ],
  "type": [
    "..."
  ],
  "definitionId": [
    "..."
  ],
  "version": [
    "..."
  ],
  "agent": [
    "..."
  ],
  "provider": [
    "..."
  ],
  "model": [
    "..."
  ],
  "engine": [
    "..."
  ],
  "credentialKind": [
    "..."
  ],
  "tier": [
    "..."
  ],
  "outcome": [
    "..."
  ],
  "startedBy": [
    "..."
  ],
  "triggerId": [
    "..."
  ],
  "rootDefinitionId": [
    "..."
  ]
}
```