Usage

MCP tools for the Usage module. See the Usage module docs 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	—