# Usage

4 calls. Every request needs the `Authorization` header: see [the overview](https://docs.maitento.com/reference.md).

## `usage.breakdown`

```http
GET /usage/breakdown
```

Totals grouped by one dimension.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fusage%2Fbreakdown).

**Query parameters**

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

**Response:** [`UsageBreakdown`](https://docs.maitento.com/reference/types/usage-breakdown.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/usage/breakdown" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const byModel = await mt.usage.breakdown({ from: new Date("2026-10-01"), groupBy: "model" });
```
```python title="Python"
mt.usage.breakdown(group_by="model", limit=10)
```

## `usage.runs`

```http
GET /usage/runs
```

Individual runs with their usage (`truncated` says more matched than were returned).

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fusage%2Fruns).

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `from` | `string` |  | The start of the range: ISO 8601 with an offset, rounded down to the hour (UTC). Default: `to` minus 7 days. |
| `to` | `string` |  | 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[]` |  | Namespace names, matched as `GET /processes` matches them. The name a deleted or renamed namespace had also matches. |
| `type` | `string[]` |  | Kinds of run: `Interaction`, `App`, `Capsule` or `CodePipeline` (case-insensitive). |
| `definitionId` | `string[]` |  | Ids of the definitions (interactions, apps, capsules, code pipelines) whose runs to include. |
| `version` | `string[]` |  | Definition versions, as `{definitionId}:{version}`. |
| `agent` | `string[]` |  | Agent names: the interaction or code pipeline agents whose turns or steps used the tokens. |
| `provider` | `string[]` |  | The AI providers that served interaction turns, such as `Anthropic`. |
| `model` | `string[]` |  | Model names. |
| `engine` | `string[]` |  | Code pipeline engines, as `CodeEngineType` names. |
| `credentialKind` | `string[]` |  | 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[]` |  | Pricing tiers, for models whose price depends on how many tokens a request uses. |
| `outcome` | `string[]` |  | How the runs ended: `InProgress`, `Finished`, `Error` or `Killed`. |
| `startedBy` | `string[]` |  | What started the runs: `User`, `Automation` or `Parent`. |
| `triggerId` | `string[]` |  | Ids of the users or automations that started the runs. |
| `rootDefinitionId` | `string[]` |  | 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. |
| `sort` | `string` |  | What to order runs by, descending: `tokens` (default), `runtime`, `execution` or `date`. |
| `limit` | `integer` |  | How many runs: 1 to 200 (clamped), default 50. |

**Response:** [`UsageRunPage`](https://docs.maitento.com/reference/types/usage-run-page.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/usage/runs" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const runs = await mt.usage.runs({ namespace: "support", sort: "cost", limit: 50 });
```
```python title="Python"
mt.usage.runs(outcome="Error", limit=50)
```

## `usage.series`

```http
GET /usage/series
```

A time series of one metric, bucketed and optionally grouped.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fusage%2Fseries).

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `from` | `string` |  | The start of the range: ISO 8601 with an offset, rounded down to the hour (UTC). Default: `to` minus 7 days. |
| `to` | `string` |  | 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[]` |  | Namespace names, matched as `GET /processes` matches them. The name a deleted or renamed namespace had also matches. |
| `type` | `string[]` |  | Kinds of run: `Interaction`, `App`, `Capsule` or `CodePipeline` (case-insensitive). |
| `definitionId` | `string[]` |  | Ids of the definitions (interactions, apps, capsules, code pipelines) whose runs to include. |
| `version` | `string[]` |  | Definition versions, as `{definitionId}:{version}`. |
| `agent` | `string[]` |  | Agent names: the interaction or code pipeline agents whose turns or steps used the tokens. |
| `provider` | `string[]` |  | The AI providers that served interaction turns, such as `Anthropic`. |
| `model` | `string[]` |  | Model names. |
| `engine` | `string[]` |  | Code pipeline engines, as `CodeEngineType` names. |
| `credentialKind` | `string[]` |  | 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[]` |  | Pricing tiers, for models whose price depends on how many tokens a request uses. |
| `outcome` | `string[]` |  | How the runs ended: `InProgress`, `Finished`, `Error` or `Killed`. |
| `startedBy` | `string[]` |  | What started the runs: `User`, `Automation` or `Parent`. |
| `triggerId` | `string[]` |  | Ids of the users or automations that started the runs. |
| `rootDefinitionId` | `string[]` |  | 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. |
| `metric` | `string` |  | The measure: `tokens` (default), `input`, `output`, `cacheRead`, `cacheWrite`, `reasoning`, `runtime`, `execution`, `runs`, `steps`, `stepRuntime`, `toolCalls`, `webSearches`, `webPages`, `webDownloads`, `imageDescriptions`, `webCredits` or `webBytes`. |
| `bucket` | `string` |  | The bucket size: `hour`, `day` or `week`. Omitted: chosen from the range's length. |
| `groupBy` | `string` |  | A dimension to split the series by (any `groupBy` a breakdown takes), or `tokenType` with `metric=tokens`. Omitted: one total series. |
| `top` | `integer` |  | How many of the largest groups get a series of their own: 1 to 10 (clamped), default 5. The rest form one "other" series. |

**Response:** [`UsageSeries`](https://docs.maitento.com/reference/types/usage-series.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/usage/series" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const daily = await mt.usage.series({ from: new Date("2026-10-01"), metric: "cost", bucket: "day" });
```
```python title="Python"
mt.usage.series(metric="cost", bucket="day", namespace="demo")
```

## `usage.summary`

```http
GET /usage/summary
```

Totals for the window.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fusage%2Fsummary).

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `from` | `string` |  | The start of the range: ISO 8601 with an offset, rounded down to the hour (UTC). Default: `to` minus 7 days. |
| `to` | `string` |  | 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[]` |  | Namespace names, matched as `GET /processes` matches them. The name a deleted or renamed namespace had also matches. |
| `type` | `string[]` |  | Kinds of run: `Interaction`, `App`, `Capsule` or `CodePipeline` (case-insensitive). |
| `definitionId` | `string[]` |  | Ids of the definitions (interactions, apps, capsules, code pipelines) whose runs to include. |
| `version` | `string[]` |  | Definition versions, as `{definitionId}:{version}`. |
| `agent` | `string[]` |  | Agent names: the interaction or code pipeline agents whose turns or steps used the tokens. |
| `provider` | `string[]` |  | The AI providers that served interaction turns, such as `Anthropic`. |
| `model` | `string[]` |  | Model names. |
| `engine` | `string[]` |  | Code pipeline engines, as `CodeEngineType` names. |
| `credentialKind` | `string[]` |  | 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[]` |  | Pricing tiers, for models whose price depends on how many tokens a request uses. |
| `outcome` | `string[]` |  | How the runs ended: `InProgress`, `Finished`, `Error` or `Killed`. |
| `startedBy` | `string[]` |  | What started the runs: `User`, `Automation` or `Parent`. |
| `triggerId` | `string[]` |  | Ids of the users or automations that started the runs. |
| `rootDefinitionId` | `string[]` |  | 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. |

**Response:** [`UsageSummary`](https://docs.maitento.com/reference/types/usage-summary.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/usage/summary" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const totals = await mt.usage.summary({ from: new Date("2026-10-01"), to: new Date("2026-11-01") });
```
```python title="Python"
mt.usage.summary(from_="2026-10-01T00:00:00Z", to="2026-10-26T00:00:00Z")
```