Cost and usage
See spend and tokens by agent, model, provider, tenant and tag, forecast the month, and set the prices spend is computed from.
After reading this page you will be able to:
- Break down spend by any dimension
- Export usage for chargeback
- Set or correct a model's price and reprice history
Read the numbers
Open AI Gateway › Cost and usage. The headline shows active agents, requests and spend for the period. The activity table lists calls with these columns: When, Agent, What, Tokens, Cost and Outcome.
| Question | Endpoint |
|---|---|
| Totals for the period (active agents, requests, spend) | GET /api/usage/headline |
| Spend by agent, model, provider, tenant, channel, principal, tool or tag | GET /api/usage/breakdown?dimension=agent |
| Over time | GET /api/usage/timeseries |
| This period against the last | GET /api/usage/compare |
| Where the month will land | GET /api/usage/forecast |
| Recent calls | GET /api/usage/activity |
Per-agent, provider and model rollups as CSV (group_by=tenant, channel, principal, ticket_id or tool adds chargeback rows) | GET /api/usage/export |
Tip
Tag agents as key=value (for example team=servicedesk), then use dimension=tag&tag_key=team for chargeback.
Prices
Cost is computed from a price per model (GET /api/usage/rates).
- Set or change a price with
PUT /api/usage/rates/{model}(optional?provider=andeffective_from). Earlier prices are kept (GET /api/usage/rates/history). - If a price was wrong, see what a period would have cost at the current card with
GET /api/usage/rates/reprice?start=.... This is read-only: it reports the difference beside the recorded spend and never rewrites recorded rows. On a multi-tenant instance only an owner may run it. - Tools can have a price too (
GET /api/usage/tool-rates,PUT /api/usage/tool-rates/{kind}/{name}), for paid APIs behind MCP servers.
Warning
A model with no price records zero cost, so a budget can never stop it. Turn on refuse_unpriced on an agent's binding: while the agent has a USD budget, calls to a model with no price are refused.