# UsageSeriesRequest

Which measure to chart, in what buckets, split how, and the usual usage filters.

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

## Fields

| Field | Type | Required | Description |
|---|---|---|---|
| `metric` | `string \| null` |  | The measure: `tokens` (default), `input`, `output`, `cacheRead`, `cacheWrite`, `reasoning`, `runtime`, `execution`, `runs`, `steps`, `stepRuntime`, `toolCalls`, `webSearches`, `webPages`, `webDownloads`, `imageDescriptions`, `webCredits` or `webBytes`. |
| `bucket` | `string \| null` |  | The bucket size: `hour`, `day` or `week`. Omitted: chosen from the range's length. |
| `groupBy` | `string \| null` |  | A dimension to split the series by (any `groupBy` a breakdown takes), or `tokenType` with `metric=tokens`. Omitted: one total series. |
| `top` | `integer \| null` |  | How many of the largest groups get a series of their own: 1 to 10 (clamped), default 5. The rest form one "other" series. |
| `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
{
  "metric": "...",
  "bucket": "...",
  "groupBy": "...",
  "top": 0,
  "from": "...",
  "to": "...",
  "namespace": [
    "..."
  ],
  "type": [
    "..."
  ],
  "definitionId": [
    "..."
  ],
  "version": [
    "..."
  ],
  "agent": [
    "..."
  ],
  "provider": [
    "..."
  ],
  "model": [
    "..."
  ],
  "engine": [
    "..."
  ],
  "credentialKind": [
    "..."
  ],
  "tier": [
    "..."
  ],
  "outcome": [
    "..."
  ],
  "startedBy": [
    "..."
  ],
  "triggerId": [
    "..."
  ],
  "rootDefinitionId": [
    "..."
  ]
}
```