Skip to main content
A budget action limits the recorded USD cost of matching requests within a UTC calendar day or month. The rule’s target and request match select which usage counts. shared combines matching usage into one allowance; per_key gives each inference key its own allowance. This guide creates a shared monthly budget of $20, then checks its spend. The same steps work for daily budgets by changing period to day.

​
Create a budget policy

Save this as budget-policy.json:
Create the policy in your active organization and workspace context:
The CLI prints a JSON array. Copy the returned id for the status command:

​
Check spending

The status output reports the UTC window, spend, remaining allowance, exhaustion, and calculation time. A monthly window starts on the first day of the month and ends on the first day of the next month. Shared budgets return one shared bucket.
The CLI prints a JSON array, one row per budget rule:
Example amounts and timestamps are illustrative. computed_at marks when status was calculated from recorded usage. Usage from earlier in the current period also counts, including usage recorded before the policy was created.

​
Audit per-key budgets

For separate allowances per inference key, set aggregation to per_key in the budget action before creating the policy. Each returned bucket identifies a key and reports its spend and remaining allowance:
Set KEY_ID to a key ID from a bucket. If it has no matching recorded usage in the current window, the query reports zero:
To inspect all key buckets, request a page. When more buckets remain, next_bucket has the form {"kind":"key","key_id":"key-id-100"}. Pass its key_id as AFTER_BUCKET for the next page:
Rule indices start at zero and follow the order in the policy’s definition.rules array. The status command requires a CLI profile with policies.read and usage.read permissions in the workspace. A request blocked by an exhausted budget receives 429 budget_exhausted with a Retry-After header.