# UsageQueryRequest

The time range and filters every `/usage` call takes. Every filter is optional; filters combine with AND across parameters and OR within one. A parameter may be repeated, and each value may also be comma-separated, except `agent`, `provider`, `model`, `engine` and `tier`, whose values are taken whole. At most 50 values per parameter. The value `~none` matches "no value" for that dimension.

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

## Fields

| Field | Type | Required | Description |
|---|---|---|---|
| `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
{
  "from": "...",
  "to": "...",
  "namespace": [
    "..."
  ],
  "type": [
    "..."
  ],
  "definitionId": [
    "..."
  ],
  "version": [
    "..."
  ],
  "agent": [
    "..."
  ],
  "provider": [
    "..."
  ],
  "model": [
    "..."
  ],
  "engine": [
    "..."
  ],
  "credentialKind": [
    "..."
  ],
  "tier": [
    "..."
  ],
  "outcome": [
    "..."
  ],
  "startedBy": [
    "..."
  ],
  "triggerId": [
    "..."
  ],
  "rootDefinitionId": [
    "..."
  ]
}
```