Skip to main content

Usage, limits and prices

See Usage controls for how limits apply.

Usage​

GET/usage

Model 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​

startdateoptional
First UTC day, inclusive. Default: 29 days before end.
enddateoptional
Last UTC day, inclusive. Default: today.
group_bystringoptional
Comma-separated: day, project, model, agent, operation. Default day.
project_idstringoptional
Only this project.

Costs​

GET/usage/costs

The 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​

startdateoptional
First UTC day, inclusive.
enddateoptional
Last UTC day, inclusive.
group_bystringoptional
Comma-separated: day, project, model, agent, key, operation. Default day.
project_idstringoptional
Only this project.

Prices​

Method and pathWhoWhat it does
GET /usage/pricesany signed-in userEvery 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 adminRemove a price.

Limits​

A limit body has any of these fields. A field left out or null has no limit.

FieldWhat it caps
monthly_budget_microsSpend in the UTC month, in micro-USD
monthly_token_capPrompt and completion tokens in the month
warn_percentThe share of a monthly cap that triggers a warning. Default 80.
rpmRequests per minute
tpmTokens per minute
allowed_modelsKeys only: the models the key may name
allowed_agentsKeys only: the agents the key may call
Method and pathWhoWhat it does
GET /projects/{project_id}/usage-limitsviewerThe project's limits, its keys' limits and scopes, the organization's, and this month's use.
PUT, DELETE /projects/{project_id}/usage-limitsplatform adminThe project's own limits.
PUT, DELETE /projects/{project_id}/keys/{key_id}/usage-limitsproject adminA project key's or agent key's limits and scopes.
PUT, DELETE /api-keys/{key_id}/usage-limitsplatform adminA personal key's limits and scopes.
GET /tenants/{tenant_id}/usage-limitsorganization memberThe organization's limits and use.
PUT, DELETE /tenants/{tenant_id}/usage-limitsplatform adminThe organization's limits.

Setting or raising a limit needs the usage_controls licence feature. Removing one never does.

Rotate a key​

Method and pathWho
POST /api-keys/{key_id}/rotateThe key's owner, or a platform admin
POST /projects/{project_id}/api-keys/{key_id}/rotateProject admin
POST /projects/{project_id}/agent-keys/{key_id}/rotateProject 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.

Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →