Budgets

What a budget is

A budget is a spend cap in USD on one scope over one window. The gateway checks every request against every budget that applies to it. A block budget at its limit rejects the request. A warn budget lets it through and adds a warning header. Spend is counted after the provider answers, from the token counts the provider reports and the LangWatch pricing catalog. Requests the gateway rejected and requests that failed at the provider add no cost.

Create a budget

Open AI Gateway > Budgets and click New budget. The drawer has these fields:

Field	Values
Name, Description	The name is required.
Applies to	Organization, Group, Team, Project, Member or Virtual key, then the target itself.
Provider	All providers, or one provider credential. Only requests served by that credential count.
Window	Per minute, Per hour, Per day, Per week, Per calendar month, Total (no reset) or Manual (reset on request).
Limit (USD)	The cap.
Start cycle on	Optional, on the cycling windows only. The date and time the periods roll from. See Cycles.
On breach	Block: reject requests at limit or Warn: tag responses, keep serving.

The New budget drawer with Project selected under Applies to, Per calendar month, a 500 dollar limit and Block on breach — The New budget drawer: Applies to with the six scope types, the provider filter, the window, the limit, the cycle anchor and On breach.

The budget is in force at once: the next request counts against it. The gateway reads budget spend from a configuration bundle refreshed every 60 seconds, so a key can serve for up to one minute after it crosses the limit. For a team, project or group target with no active key that can reach it, the drawer refuses the budget with gateway_budget_scope_unreachable and offers Create it anyway. Use it when you provision the budget before the keys. Per-end-user budgets are created over the API. See Per end user.

Scopes

Scope	Counts
`organization`	Every request in the organization.
`team`	Every request whose trace project belongs to the team.
`project`	Every request whose traces land in the project.
`virtual_key`	Every request on this key.
`principal`	Every request by this person, on any key with them as principal. Member in the drawer.
`group`	Each member of the group, individually. One budget, one allowance per member. Needs the ClickHouse spend ledger.
`attributed_user`	Each end user of your product, individually, on one key or one project. Needs the ClickHouse spend ledger.

One request is checked against all of them. For example, a request on key acme-support-agent in project support of team platform counts against the key’s, the project’s, the team’s and the organization’s budgets, and against the principal and group budgets when the key has a principal. A group budget gives each member their own allowance: a

10 per day budget on group `engineering` caps each engineer at

10, and one member’s spend never counts against another. It applies only to keys with a principal. Telling members apart needs the ClickHouse spend ledger, so a deployment that reads budget spend from Postgres only refuses the create with group_budget_requires_clickhouse. An attributed_user budget is refused the same way.

Per end user

An attributed_user budget is a template on one virtual key or one project: each distinct end user seen there gets the limit per window. You create one budget, and buckets appear per end user on first spend.

curl -sS https://app.langwatch.ai/api/gateway/v1/budgets \
  -H "X-Auth-Token: $LANGWATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": { "kind": "attributed_user", "anchor_virtual_key_id": "vk_..." },
    "name": "acme per-user cap",
    "window": "month",
    "limit_usd": "25",
    "on_breach": "block"
  }'

The end user comes from the request: the X-LangWatch-End-User-Id header, then the X-Litellm-End-User-Id header, then the OpenAI user body field. While such a budget is active on the key, a request with no end-user id is rejected with HTTP 400 end_user_required. Read one user’s spend and caps with GET /api/gateway/v1/end-users/:id/spend. See Billing and spend events.

Block and warn

`on_breach`	At the limit	From 80 percent
`block`	HTTP 402 `budget_exceeded`	`X-LangWatch-Budget-Warning` header
`warn`	Request served, header set	`X-LangWatch-Budget-Warning` header

The 402 body is an OpenAI-shaped error with the budget in error.meta:

{
  "error": {
    "type": "budget_exceeded",
    "code": "budget_exceeded",
    "message": "...",
    "meta": {
      "budget_id": "NtdzZ9i9EctuXAeZ1oFyr",
      "budget_scope": "virtual_key",
      "budget_window": "month"
    }
  }
}

budget_scope tells your application which allowance ran out: attributed_user is the end user’s own cap, virtual_key is the tenant’s cap. The warning header lists every budget at or past 80 percent as scope:percent, comma separated, for example X-LangWatch-Budget-Warning: project:84,virtual_key:100. A provider-filtered budget appears as scope/provider_id:percent. A block budget with a Provider filter removes that provider from the request’s provider chain instead of rejecting the request. The request is rejected only when no provider is left. Two webhook events fire once per period: gateway.budget.threshold_crossed at 80 percent and gateway.budget.breached at the limit, on warn budgets too. See Webhooks.

Windows and cycles

The cycling windows (minute, hour, day, week, month) roll on the calendar in UTC: a day resets at 00:00, a week on Monday 00:00, a month on the first. Set Start cycle on (cycle_anchor_at on the API) to roll from your own date instead. Anchored on the 17th at 09:00, every period starts on the 17th at 09:00. A monthly anchor past the 28th clamps into shorter months. The anchor is fixed at creation; total and manual refuse one with gateway_budget_cycle_anchor_invalid. total never resets. manual accrues until you reset it:

curl -sS -X POST https://app.langwatch.ai/api/gateway/v1/budgets/<budget_id>/reset \
  -H "X-Auth-Token: $LANGWATCH_API_KEY"

A reset moves the period boundary to now. Recorded spend and emitted spend events never change. On an attributed_user budget, add ?end_user_id=<id> to reset one end user’s bucket.

See the spend

AI Gateway > Budgets lists every budget with its spent amount against its limit, its window, its breach mode and its next reset.

The Budgets list with an organization budget at 0 percent, a block budget at 100 percent and a warn budget at 85 percent — AI Gateway > Budgets: spent against limit per budget, the window, the breach mode and the next reset. The block budget is at 100 percent, the warn budget at 85.

Click a budget for its 20 most recent debits, with the time, the virtual key, the model, the amount and the status.

The budget detail page for acme-block-budget with the utilization bar full and red, Window day, On breach block, the Identity block and the Recent activity table — A breached block budget opened: $0.05822 spent of a $0.05 daily limit, 100 percent used, the next reset, and under Recent activity the requests that spent it.

AI Gateway > Usage shows total spend, requests, cost per request, top virtual keys and top models over a period, with a CSV export.

Manage budgets from the CLI

langwatch gateway-budgets create \
  --name "engineering monthly cap" \
  --scope team --team <team_id> \
  --window month --limit 5000 --on-breach block

langwatch gateway-budgets list --scope-type team,project
langwatch gateway-budgets update <budget_id> --limit 6000
langwatch gateway-budgets reset <budget_id> --reason "new billing period"
langwatch gateway-budgets archive <budget_id>

Manage budgets over REST

Method and path	Permission
`GET /api/gateway/v1/budgets`	`gatewayBudgets:view`
`POST /api/gateway/v1/budgets`	`gatewayBudgets:create`
`GET /api/gateway/v1/budgets/:id`	`gatewayBudgets:view`
`PATCH /api/gateway/v1/budgets/:id`	`gatewayBudgets:update`
`POST /api/gateway/v1/budgets/:id/reset`	`gatewayBudgets:update`
`DELETE /api/gateway/v1/budgets/:id` (archive)	`gatewayBudgets:delete`

Field by field: Budgets API reference. A virtual key’s own budget can also be set inline on the key: see Virtual keys.

Get Started

SDK Integration

Virtual Keys & Budgets

Billing & Metering

Governance

Providers

Features

API Reference

Self-Hosting

Cookbooks

What a budget is

Create a budget

Scopes

Per end user

Block and warn

Windows and cycles

See the spend

Manage budgets from the CLI

Manage budgets over REST

​What a budget is

​Create a budget

​Scopes

​Per end user

​Block and warn

​Windows and cycles

​See the spend

​Manage budgets from the CLI

​Manage budgets over REST

What a budget is

Create a budget

Scopes

Per end user

Block and warn

Windows and cycles

See the spend

Manage budgets from the CLI

Manage budgets over REST