Skip to content
Docs menu

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.

View .md

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:

  1. Open /budgets, go to New budget.
  2. Applies to: Gear. Gear: deep.
  3. Window: Daily. Limit (USD): 50. Warn at (%): 80.
  4. At the limit: Switch to a cheaper model. Cheaper model: gpt-5.4-mini.
  5. 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.