# Usage

> MCP tools for the Usage module. See the [Usage module docs](/docs/modules/usage) for permissions and data model.

# Usage

MCP tools for the Usage module. See the [Usage module docs](/docs/modules/usage) for permissions and data model.

### `list-usage-events`

List usage events

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `agent_id` | `string` | no | Filter by agent public ID |
| `generation_id` | `string` | no | Filter by generation public ID |
| `trace_id` | `string` | no | Filter by trace public ID |
| `actor_id` | `string` | no | Filter by the actor (end user) the usage is attributed to. An actor that does not exist in scope yields an empty page. |
| `session_id` | `string` | no | Filter by the session the usage was produced in. A session that does not exist in scope yields an empty page. |
| `ai_provider_id` | `string` | no | Filter by the provider record the spend was billed against. A provider that does not exist in scope yields an empty page. |
| `orchestration_run_id` | `string` | no | Filter by the orchestration run that metered the event. A run that does not exist in scope yields an empty page. |
| `orchestration_id` | `string` | no | Filter by orchestration — the events of the runs it started itself, not the subtree its `loop` or `sub_orchestration` nodes started. An orchestration that does not exist in scope yields an empty page. |
| `model` | `string` | no | Filter by the as-billed SKU the event recorded. Matched as recorded, so it still selects events whose provider has since been deleted. |
| `trigger_id` | `string` | no | Filter by the trigger that initiated the generation |
| `action_id` | `string` | no | Filter by logical action id |
| `meter_type` | `string` | no | Filter by meter type (e.g. `llm_tokens`, `compute_execution`, `api_request`, `storage`) |
| `source` | `string` | no | Filter by what the spend was incurred for. `eval` is an eval run's item generations and `eval_judge` an `llm_judge` scorer's own completion, so verification spend is `source` in (`eval`, `eval_judge`); `embedding` is any embedding call. Ordinary agent traffic carries no source and is matched by none of them. |
| `limit` | `number` | no | — |
| `offset` | `number` | no | — |

### `get-usage-aggregate`

Get aggregated usage for a project

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | yes | Project public ID to aggregate usage for |
| `group_by` | `string` | no | Dimension to bucket by. Omit it to skip bucketing entirely: `totals` still describes the whole window and `groups` is an empty page, which is what "what did this one thing cost" wants. A value naming no dimension is a `400`. `day` buckets on the event's UTC calendar day; the others bucket on the matching column. `ai_provider` buckets on the provider the spend was billed against — a routed generation's serving target, or the agent's pinned provider. `model` buckets on the model id *and* the provider that served it, so one model name served by two providers is two groups (see `ai_provider_id`). `source` buckets by what the spend was incurred for (`eval`, `eval_judge`), which is how verification spend is priced apart from the traffic serving real users; unlabelled traffic collapses into the single `null` bucket. `orchestration_run` buckets on the orchestration run the event belongs to — a standalone generation runs no orchestration and collapses into the single `null` bucket, so the bucket count under this dimension is not a count of runs. |
| `include` | `string` | no | Optional extras to compute. The only value is `distinct`, which adds `totals.distinct` — one distinct-entity count per attribution column. It is opt-in because each key costs the database one extra sort of the window, so the default response keeps its cost whatever the event table grows to carry; a caller counting entities sends one request at `limit=1&include=distinct`. Any other value is a `400`. |
| `from` | `string` | no | Inclusive lower bound (ISO-8601 timestamp) on the event created_at. Omit for no lower bound. |
| `to` | `string` | no | Inclusive upper bound (ISO-8601 timestamp) on the event created_at. Omit for no upper bound. |
| `meter_type` | `string` | no | Narrow the rollup to one meter type (e.g. `llm_tokens`, `compute_execution`, `api_request`, `storage`). Omit to include every meter. An unknown type yields an empty rollup, not an error. |
| `session_id` | `string` | no | Narrow the whole rollup — every bucket, `totals` and `totals.distinct` alike — to one session's traffic. Combines with `group_by`: `group_by=day&session_id=…` is a conversation's spend per day, `group_by=model` is the same spend split by model. An id naming no session in this project yields an empty rollup, never the project total. |
| `actor_id` | `string` | no | The same narrowing, for one end user across every session they appear in. This is the figure behind a `scope: actor`, `metric: cost_usd` quota — what that actor has spent, against the cap it is held to. |
| `agent_id` | `string` | no | Narrow to one agent's traffic, across every session, run and trigger that dispatched it. |
| `ai_provider_id` | `string` | no | Narrow to the spend billed against one provider record — a routed generation's serving target, or the agent's pinned provider. |
| `orchestration_run_id` | `string` | no | Narrow to the events one orchestration run metered. |
| `orchestration_id` | `string` | no | Narrow to the runs of one orchestration — the runs it started itself, never the subtree a `loop` or `sub_orchestration` node started under it, which is metered against the child orchestration where it was incurred. Additive: summed across a project's orchestrations the figures reach the project total exactly once. For the subtree figure of a single invocation, read `usage` on the run. |
| `generation_id` | `string` | no | Narrow to one generation's events. A generation writes more than one when it meters several dimensions (tokens and compute). |
| `trace_id` | `string` | no | Narrow to the events recorded under one trace. |
| `model` | `string` | no | Narrow to one model, matched against the as-billed SKU the event recorded. A value naming no model yields an empty rollup, not an error. Under `group_by=model` this is a single-bucket rollup; under any other dimension it is that model's spend split by the dimension. |
| `source` | `string` | no | Narrow by what the spend was incurred for — `eval` and `eval_judge` are verification spend. Ordinary traffic carries no source, so it cannot be selected by this filter; omit the filter for everything. |
| `trigger_id` | `string` | no | Narrow to the spend one trigger initiated. Matched as recorded rather than resolved, so it still selects the spend of a trigger that has since been deleted. |
| `action_id` | `string` | no | Narrow to one caller-supplied action label, for per-action spend. Matched as recorded, like `trigger_id`. |
| `limit` | `number` | no | Maximum number of `groups` entries to return. Clamped to 100. Does not affect `totals` or `groups.total`, which describe the whole window. |
| `offset` | `number` | no | Number of `groups` entries to skip |

### `list-usage-thresholds`

List usage thresholds

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | no | Filter by project public ID |
| `limit` | `number` | no | Maximum number of results to return |
| `offset` | `number` | no | Number of results to skip |

### `create-usage-threshold`

Create a usage threshold

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | yes | — |
| `metric` | `string` | yes | — |
| `window` | `string` | yes | — |
| `threshold` | `number` | yes | Must be greater than 0 |

### `delete-usage-threshold`

Delete a usage threshold

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `threshold_id` | `string` | yes | Threshold public ID |

### `get-usage-receipt`

Get a generation or orchestration-run billing receipt

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `generation_id` | `string` | no | Generation public ID. Mutually exclusive with orchestration_run_id. |
| `orchestration_run_id` | `string` | no | Orchestration run public ID. Returns the receipt summed across every generation the run metered. Mutually exclusive with generation_id. |

### `get-price-book`

Get the price book

#### Arguments

This tool takes no arguments.

### `upsert-price-book`

Upsert price-book rows

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `prices` | `array<object>` | yes | — |