Skip to content

Configure Budgets and Operating Caps

Purpose

Set allocation ceilings and operating caps for Organization, Team, owner, key and customer dimensions without confusing overlapping enforcement with billed usage.

Prerequisites

budgets.allocate sets allocations. budgets.manage manages operating caps; budgets.read reads constraint detail and usage.read reads financial summaries. Exact ordinary-key managers may edit key-local operating caps. Deployment access managers have a bounded managed-execution cap path.

Procedure

  1. Open Manage → Budgets and choose Organization or one authorized Team from the scope buttons. The selected scope is highlighted. All Teams is reporting-only.
  2. Distinguish allocation from operating policy. An allocation distributes a governance ceiling; an operating cap narrows actual use. Every applicable ceiling must allow the next physical work.
  3. Choose a Metric. The Window and Unit offered follow it, so the editor cannot submit a combination the service would reject: spend over daily/monthly/lifetime windows in USD; requests per minute in logical ingress or upstream attempts; tokens per minute; or concurrent capacity. The API still rejects an unsupported combination.
  4. Set a nonnegative limit. A spend cap is entered in Limit (USD) as dollars, with at most six decimal places; the Console converts it to the USD micros the API and the YAML reference store. Every other unit takes a whole number, in Limit (tokens), Limit (requests) or Limit (upstream attempts). 0 blocks that dimension; leave the field blank (null in the API) to remove that local cap and keep ancestor ceilings. For an existing policy, select Update cap beneath its field; its heading reads the cap in words and money, such as "Operating spend cap · monthly (UTC) · $25.00 · revision 3". Without the permission that cap's kind needs — budgets.allocate for an allocation ceiling, budgets.manage for an operating cap — the same cap is read-only and its limit reads as one line, "Limit: $25.00". For a new policy, expand Add a budget policy, complete the labeled fields, and select Add cap. Save using the current revision.
  5. For an ordinary key, use its detail to set a local cap if you have exact key-management authority. For a managed deployment, open the Agent's Live tab and its access/limit controls so its access and cap revisions are updated/audited together.
  6. Make one bounded request and inspect Usage plus its canonical Request. Under finite spend caps, the model route must have pricing and a finite supported output bound before reservation.

Expected result

Every actual provider retry, model round and business tool dispatch has a separate reservation/claim/settlement. One ledger fact may feed multiple governing meters without duplicate billing. Managed wrappers have no financial attempt. Session cost contains only assigned facts. Missing pricing/usage remains unknown, not zero.

Verification

Use a synthetic low cap to verify an allowed bounded call and safe admission denial before upstream work. Confirm rotation leaves counters unchanged. Inspect an active reservation and its settlement. A viewer without budget detail must not receive numeric ancestor ceilings in an error.

Bounded tool charges

For tools under finite spend caps, configure the actual tool's costPerCallMicros in reviewed YAML. An explicit 0 declares known-zero cost; absent pricing remains unknown and can be refused before dispatch. Every physical business call is counted once, with no model-token charge; model rounds are metered separately. Restart gateway/Console after price changes. See tool pricing.

Judge spend

Each Team that saves an evaluator version gets an evaluation identity: a managed service account and a virtual key with no secret, which every LLM judge call is funded by. Its cap is an ordinary operating spend cap on that key, entered in USD, written from Evaluate → Evaluators as Judge spend and readable under Manage → Budgets with the key as the scope. The Organization's allocation on the Team remains the ceiling above it, and the Team's own operating caps still apply: a judge call must pass every one of them. When any of them refuses, the judgment is not lost — the execution waits as Delayed with the reason and is retried once the window it exceeded rolls over. While the cap is reached, auto-evaluation stops sampling as well: the Team's auto-evaluations skip the traffic that finishes, and they resume with new traffic after the window rolls over rather than judging what they passed over, while the judgments already queued are never discarded. Managed evaluation keys cannot be read or edited through ordinary key APIs.

Failure recovery

On 409, reload and review the actual target revision. Reduce the requested output bound or change the permitted cap through the correct authority. Active I/O renews its existing lease without another request/spend admission. Unknown termination retains its debit and holds capacity until confirmation or actual lease recovery; do not clear evidence or blindly replay work.