Usage, limits and prices
See Usage controls for how limits apply.
Usage
/usageModel calls and tokens, grouped. A platform admin sees everything. Anyone else sees the projects they have a role on, and their own calls that belong to no project.
Query parameters
startdateoptionalend.enddateoptionalgroup_bystringoptionalday, project, model, agent, operation. Default day.project_idstringoptionalCosts
/usage/costsThe cost ledger, grouped, with the same visibility as GET /usage. Each row has the call count, the cost in micro-USD, prompt and completion tokens, and how many calls had no price.
Query parameters
startdateoptionalenddateoptionalgroup_bystringoptionalday, project, model, agent, key, operation. Default day.project_idstringoptionalPrices
| Method and path | Who | What it does |
|---|---|---|
GET /usage/prices | any signed-in user | Every price. |
PUT /usage/prices/{model} | platform admin; licence usage_controls | {"input_micros_per_mtok", "output_micros_per_mtok", "request_micros"}, in micro-USD. {model} is the name callers send, or * for every model without its own price. Phone minutes are the model sip-minutes, priced per request. |
DELETE /usage/prices/{model} | platform admin | Remove a price. |
Limits
A limit body has any of these fields. A field left out or null has no limit.
| Field | What it caps |
|---|---|
monthly_budget_micros | Spend in the UTC month, in micro-USD |
monthly_token_cap | Prompt and completion tokens in the month |
warn_percent | The share of a monthly cap that triggers a warning. Default 80. |
rpm | Requests per minute |
tpm | Tokens per minute |
allowed_models | Keys only: the models the key may name |
allowed_agents | Keys only: the agents the key may call |
| Method and path | Who | What it does |
|---|---|---|
GET /projects/{project_id}/usage-limits | viewer | The project's limits, its keys' limits and scopes, the organization's, and this month's use. |
PUT, DELETE /projects/{project_id}/usage-limits | platform admin | The project's own limits. |
PUT, DELETE /projects/{project_id}/keys/{key_id}/usage-limits | project admin | A project key's or agent key's limits and scopes. |
PUT, DELETE /api-keys/{key_id}/usage-limits | platform admin | A personal key's limits and scopes. |
GET /tenants/{tenant_id}/usage-limits | organization member | The organization's limits and use. |
PUT, DELETE /tenants/{tenant_id}/usage-limits | platform admin | The organization's limits. |
Setting or raising a limit needs the usage_controls licence feature. Removing one never does.
Rotate a key
| Method and path | Who |
|---|---|
POST /api-keys/{key_id}/rotate | The key's owner, or a platform admin |
POST /projects/{project_id}/api-keys/{key_id}/rotate | Project admin |
POST /projects/{project_id}/agent-keys/{key_id}/rotate | Project admin |
Body: {"overlap_hours": 24}, from 0 to 720. The key keeps its id, name, restriction, expiry, limits and scopes, and gets a new secret, returned once. The old secret works until the overlap ends, never past the key's own expiry. A revoked or expired key, a key Orchestrate manages for a code agent deployment, and the platform's service keys can't be rotated here.