Budgets and spend guards
Set daily, monthly or lifetime spend limits per member, API key, key group, gear or project that warn first, then block requests or switch them to a cheaper model.
A budget limits what one member, API key, key group, gear or project may spend in a window. It warns at a share of its limit and, at the limit, either refuses requests or sends them to a cheaper model you name. Budgets are checked on every /v1 request without slowing it down: spend per budget is refreshed in the background every 10 seconds.
The /budgets page lists your budgets with live bars (spent against limit) and a forecast for each, the form to add one, the window's spend per member and per gear, and recent warnings and limits. It refreshes every 30 seconds while open.
Add a budget
Limit the deep gear to $50 a day, switching to a cheaper model at the limit:
- Open
/budgets, go to New budget. - Applies to: Gear. Gear:
deep. - Window: Daily. Limit (USD):
50. Warn at (%):80. - At the limit: Switch to a cheaper model. Cheaper model:
gpt-5.4-mini. - Create.
The venom CLI names the engaged gear on every request (x-venom-gear). Any other client can do the same:
curl https://cloud.usevenom.dev/v1/chat/completions \
-H "Authorization: Bearer vck_…" \
-H "x-venom-gear: deep" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-5.4", "messages": [{"role": "user", "content": "hello"}]}'Fields
| Field | Values | Default |
|---|---|---|
| Applies to | Member, API key, Key group, Gear, Project | Key group |
| Subject | the member, key or key group from a list; a gear or project name typed in | required |
| Window | Monthly or Daily (UTC); Lifetime (no reset) for projects only | Monthly |
| Limit (USD) | 0 or more, in cents | required |
| Warn at (%) | 1 to 100 | 80 |
| At the limit | Block requests, or Switch to a cheaper model | Block requests |
| Cheaper model | the model id to switch to | required with Switch |
- A member budget counts the keys that member created, including keys a CLI login made under their approval.
- A key budget follows the key through rotations.
- A gear budget counts requests that name the gear in
x-venom-gear. Gear names start with a letter, then letters, digits,.,_or-. - A project budget counts requests tagged
x-venom-project: <name>, else the key's project (set under API keys). Project names are lower case letters, digits and. _ : / -. Project budgets also appear on the Usage, Projects page. - A customer budget, in the customer's currency, is set on that customer's page, not here.
There is one budget per subject and window, and at most 200 per organisation. The organisation-wide monthly spend cap is separate: it is on the Usage page. Each product's own daily AI limit (People, Notes, Chat agents, Outreach, Tasks, Support and the rest) is on AI spend.
What a request sees
| Situation | Response |
|---|---|
| At or past the warn share | Served, with x-venom-spend-warning naming the budget, the spend and the reset time. |
| At the limit, Switch | Served by the cheaper model, with x-venom-spend-downgrade naming the budget, the model asked for and the model used. |
| At the limit, Block | 429 spend_limit_reached, with x-venom-spend-reset (when the budget resets, ISO time) and a cheaper model you serve as a suggestion. A lifetime budget never resets. |
Crossing 80% and 100% writes budget.warning and budget.reached to the audit log once per window, and sends the same events to your webhooks. Editing a budget resets those alerts.
Who can do what
| Action | Permission | Roles |
|---|---|---|
See /budgets |
usage:read |
owner, admin, developer, billing, viewer |
| Create, edit, remove budgets | billing:manage or org:manage |
owner, admin, billing |
Troubleshooting
| Message | Cause and fix |
|---|---|
| Changing budgets needs billing:manage or org:manage. | Ask an owner, admin or billing member. |
| Name the gear (a letter, then letters, digits, . _ -). | Fix the gear name. |
| Name the project (lower case letters, digits and . _ : / -). | Fix the project name. |
| No members to choose yet | The subject list is empty for that scope: no members, keys or key groups yet. |
| A gear budget never moves | The client doesn't send x-venom-gear. The venom CLI does; other clients must add the header. |
429 spend_limit_reached on /v1 |
A budget with Block is at its limit. Wait for x-venom-spend-reset, raise the limit, or switch it to a cheaper model. |
Spend anomalies (sudden jumps per key, member, model or gear) are a separate check; they arrive in the console's notifications, where you can also pause a key.
Related
- Usage and chargeback: spend, the monthly spend cap, projects and statements.
- Pricing and invoice reconciliation: the prices budgets count.
- Organisation gears: the gears a gear budget limits.