burn
Browse docs

On this page

Budgets

A budget is a daily spend limit stored in config.json. It is checked by the proxy, not by the provider.

Set a budget

burn budget daily 5

The amount is in US dollars. It must be a positive number. The command prints whether the budget is warn-only or blocking:

daily budget set to $5.0000. burn warns once per process.

Add --block to make the proxy reject requests after the limit is reached:

burn budget daily 5 --block

Warn or block

Without --block, burn compares today's spend to the limit when a request arrives. Once the limit is reached, it prints one warning per proxy process and keeps forwarding requests:

burn: daily budget of $5.0000 is used up (spent $5.0213 today). Requests keep flowing.

With --block, the proxy answers the request itself with HTTP 429 and does not contact the provider:

{
  "error": "daily budget reached",
  "spent": 5.0213,
  "budget": 5,
  "hint": "raise it with: burn budget daily <usd>, or turn blocking off with: burn budget daily <usd>"
}

The check happens before the request is forwarded. A request that was already in flight when the limit was crossed is not cancelled; it finishes and is logged.

Check and remove

burn budget

Prints the current limit and mode. If no budget is set, it says so and shows the command to set one.

burn budget off

Removes the budget. Requests flow normally again.

How the limit is calculated

  • The window is today in local time: from local midnight to now.
  • The sum is the cost of rows logged in that window.
  • Rows with no cost contribute zero to the sum, because burn does not guess.
  • The budget is global. It is not per provider, per model, or per tag.
  • The proxy reads config.json for each request. A change applies to the next request without restarting the proxy.

Because the budget uses the cost stored on the row, a later burn price recalc can change today's total. The next request sees the updated total.

What it does not do

A budget is not a hard cap on your provider account. It only sees traffic routed through the proxy. Anything that calls the provider directly is invisible, and a provider-side limit is the only way to cap that traffic.

The proxy also has no authentication. A budget is not an access control; it is a local guardrail.