Relay: budgets

What is counted

Relay does not see your provider invoice. It computes the cost of each request from the provider's published list price for the model (input, output, cache-read and cache-write tokens, as reported in the provider's response) and adds it to the environment's month-to-date total. On your own keys the real charge may be lower if you have negotiated discounts; the budget is therefore conservative, which is the right direction for a limit. The price table is published in the console and in the changelog whenever a provider changes it.

Streaming responses are settled when the terminal usage event arrives. If a stream is cut before usage is known, Relay estimates from the request size and marks the trace usage_estimated.

Hard mode: no overspend under concurrency

A naïve check — read the total, compare, then forward — lets ten simultaneous requests all pass when there is room for one. Relay instead reserves an estimated amount atomically before forwarding and settles the actual amount afterwards:

1. Estimate from the request (prompt tokens × input price + max_tokens × output price, capped by a per-model default).
2. Atomically add the estimate to the month-to-date total; if the result exceeds the limit, roll back and return 402 budget_exceeded.
3. Forward the request; on completion replace the reservation with the actual cost.

The consequence: near the limit, a few requests may be refused that would have fitted; none will be admitted that would not. Reservations abandoned by a crashed instance expire after five minutes.

Soft mode

Traffic is never refused. Alerts fire once per threshold per month:

• 80 % — email to environment admins and owners; webhook budget.warning.
• 100 % — email and webhook budget.exceeded; the dashboard shows the environment in red.

Raising or resetting

Owners can raise an environment's budget at any time; the change is audited. Budgets reset on the first of the month at 00:00 UTC. There is no carry-over.

Reading the headers

X-Relay-Budget-Used: 4821.37     # month-to-date, USD, after this request
X-Relay-Budget-Limit: 5000       # absent when no budget is set
X-Relay-Budget-Mode: hard

Webhook payload

{ "type": "budget.exceeded", "org": "org_…", "environment": "prod", "month": "2026-11",
  "used": 5000.12, "limit": 5000, "mode": "hard", "at": "2026-11-18T09:14:02Z" }

Webhooks are signed with an HMAC-SHA256 header X-Relay-Signature over the raw body using the environment's webhook secret.