Skip to navigation
Billing and Budgets

Budgets

Per-call maximums and spend limits for the account, a key or a session

View as Markdown

A budget limits what can be spent before a call runs. Budgets are checked when the hold is taken, together with the runs already in flight, so parallel calls cannot overrun them.

FieldValuesMeaning
scopeaccount, key, sessionWhat the budget covers. key and session need scope_ref (the key id or session_id).
periodday, week, month, totalWhen the limit resets. Periods use UTC; weeks start on Monday.
limit_usddecimal string or nullMost that may be charged in the period.
per_call_max_usddecimal string or nullCaps max_cost_usd for every call in scope.
statusactive, disabledDisabled budgets are ignored.

Every active budget that applies to a call counts: an account budget, the budget of the key or OAuth grant making the call, and the budget of the call’s session_id.

Create one

Managing budgets needs the manage scope (the dashboard has it; API keys get it only when created with it).

curl -s https://api.agentrouter.to/v1/budgets \
  -H "Authorization: Bearer $AGENTROUTER_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Research agent", "scope": "session", "scope_ref": "research-7", "period": "total", "limit_usd": "1", "per_call_max_usd": "0.05"}'

Change or disable it with PATCH /v1/budgets/{budget_id}, or in Settings → API.

When a budget stops a call

The run is recorded as BLOCKED with BUDGET_EXCEEDED (or MAX_COST_EXCEEDED when the per-call maximum is lower than what the input can cost) and nothing is charged. An agent should report the reason and the remaining budget to the user rather than splitting the work into smaller calls to get around it.

Budgets and agents

  • Give each agent task a session_id and a session budget so one runaway task cannot spend the whole wallet.
  • Give each CI job or server its own API key with a key budget.
  • MCP hosts connected with OAuth are callers too; their runs show the host’s name and count against key budgets for that grant.