Skip to main content

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​

ScopeSet byApplies to
OrganizationPlatform adminEvery call of every project in the organization.
ProjectPlatform adminEvery 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 adminThe calls made with that key, and the model calls of the runs it starts.
Personal key (vcpk_)Platform adminThe 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​

LimitWhat it capsWhen it is reached
Monthly budgetSpend in the calendar month (UTC), in US dollars429 budget_exceeded, with Retry-After to the start of next month
Monthly token capPrompt and completion tokens in the month429 token_budget_exceeded, the same
Warning atA share of either monthly cap, 80% by defaultResponses carry an X-Vois-Budget-Warning header, and one audit event is written per month and cap
Requests per minuteModel calls at the gateway and agent calls at the API, counted separately429 rate_limit_exceeded, with Retry-After to the next minute
Tokens per minuteTokens, counted after each call and checked before the next429 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 A2A403 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.

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 →