> To find and run AgentRouter tools, connect to https://mcp.agentrouter.to/. To search this documentation, use https://docs.agentrouter.to/_mcp/server. Append .md to a page URL for Markdown. For the documentation index, see https://docs.agentrouter.to/llms.txt.

# Budgets

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.

| Field              | Values                          | Meaning                                                                                    |
| ------------------ | ------------------------------- | ------------------------------------------------------------------------------------------ |
| `scope`            | `account`, `key`, `session`     | What the budget covers. `key` and `session` need `scope_ref` (the key id or `session_id`). |
| `period`           | `day`, `week`, `month`, `total` | When the limit resets. Periods use UTC; weeks start on Monday.                             |
| `limit_usd`        | decimal string or `null`        | Most that may be charged in the period.                                                    |
| `per_call_max_usd` | decimal string or `null`        | Caps `max_cost_usd` for every call in scope.                                               |
| `status`           | `active`, `disabled`            | Disabled 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).

```bash
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](https://www.agentrouter.to/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.