---
title: Budgets and spend guards
description: 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.
section: cloud
order: 28
audience: [user, operator]
sources: [services/nodejs-cloud/app/(console)/(shell)/budgets, services/nodejs-cloud/components/budgets, services/nodejs-cloud/lib/budget/guard-math.ts, services/nodejs-cloud/lib/budget/guards.ts]
features: [cloud.console-budgets]
---

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 {#example}

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:

```bash
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 {#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](/docs/cloud/ai-spend.md).

## What a request sees {#headers}

| 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 {#roles}

| 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 {#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 {#related}

- [Usage and chargeback](/docs/cloud/console-usage.md): spend, the monthly spend cap, projects and statements.
- [Pricing and invoice reconciliation](/docs/cloud/console-prices.md): the prices budgets count.
- [Organisation gears](/docs/cloud/console-gears.md): the gears a gear budget limits.
