Usage controls
Orchestrate can cap what an organization, a project or a key spends and how fast it calls. Every model call through the Model Gateway, and every agent call through the Agent API and A2A, is checked against the limits of everything it belongs to before it runs.
Where limits apply
| Scope | Set by | Applies to |
|---|---|---|
| Organization | Platform admin | Every call of every project in the organization. |
| Project | Platform admin | Every call of the project: its agents' model calls, Agent API and A2A calls, agent tool calls and code agents' calls. |
Project key (vcpj_) or agent key (vcag_) | Project admin | The calls made with that key, and the model calls of the runs it starts. |
Personal key (vcpk_) | Platform admin | The key's own Model Gateway calls. |
A call is checked against every scope it belongs to, so a key is only ever narrower than its project, and a project narrower than its organization. A scope with no limits set has no limit.
A console user's own session, such as a Playground chat with a model, has no project and no key, and isn't limited. The platform's own service keys can't be limited, and neither can the keys Orchestrate mints for a code agent's deployment: limit its project instead.
Limits
| Limit | What it caps | When it is reached |
|---|---|---|
| Monthly budget | Spend in the calendar month (UTC), in US dollars | 429 budget_exceeded, with Retry-After to the start of next month |
| Monthly token cap | Prompt and completion tokens in the month | 429 token_budget_exceeded, the same |
| Warning at | A share of either monthly cap, 80% by default | Responses carry an X-Vois-Budget-Warning header, and one audit event is written per month and cap |
| Requests per minute | Model calls at the gateway and agent calls at the API, counted separately | 429 rate_limit_exceeded, with Retry-After to the next minute |
| Tokens per minute | Tokens, counted after each call and checked before the next | 429 token_rate_limit_exceeded |
| Allowed models (keys only) | The models a key may name. Also narrows GET /v1/models. | 403 model_not_in_key_scope |
| Allowed agents (keys only) | The agents a key may call through the Agent API or A2A | 403 agent_not_in_key_scope |
A monthly cap is a hard stop: the call that crosses it runs and is charged, and the next is refused. An agent run that hits a monthly cap fails and isn't retried. A per-minute limit is retried.
If the limit tables can't be read, calls run unchecked and a warning is logged, so a cost control never becomes an outage. Model access stays closed in the same situation. See Model access.
Set limits
- A project and its keys. Open Projects, choose the project, and open Budgets and limits. It shows the project's limits, each key's limits and scopes, the organization's, and this month's use.
- An organization. Open Organizations, choose the organization, and open its budget and limits panel.
Setting or raising a limit, or a price, needs the usage_controls licence feature. Removing a limit never does, and limits already set are enforced whatever the licence says, so a lapsed licence can't lift a cost cap.
Prices and the cost ledger
A platform admin sets prices under Usage > Model prices, per model name as callers send it: a price per million input tokens, per million output tokens, and per request. A price on * covers every model without its own. A call to a model with no price costs nothing and is marked unpriced. A change of price applies from the next call.
Every metered call writes a row to the cost ledger: chat, embeddings, transcription, speech, cache hits at zero cost, and phone call minutes. Each row records the project, agent, key and kind of key.
Usage shows spend by model, project, agent, key and day. Through the API, GET /usage/costs groups the ledger by day, project, model, agent, key or operation.
Rotate a key
Rotating a key gives it a new secret and keeps everything else: its id, name, agent restriction, expiry, limits and scopes. The old secret keeps working for an overlap you choose, 24 hours by default and up to 720. An overlap of 0 stops it at once, which is the answer to a leaked key that should keep its identity. To stop a key altogether, revoke it.
- Your own personal key: on API keys > Personal keys.
- An agent key: on API keys > Agent keys, by a project admin.
- A project key: on Projects > Budgets and limits, by a project admin.
The platform's own service keys are rotated by changing their Helm value and upgrading. See Configuration.