3 kinds of limit apply to every paid request. It starts only when all of them have room.

| Limit | Set in | Default |
| --- | --- | --- |
| Session budget | `budget` when starting a session, or `session.budget.session` in YAML | $250 |
| Agent or handler limits | `session.budget.day`, `week`, `month` in YAML | $1,000 a day, $10,000 a week, $40,000 per 28 days |
| Account limits | **Billing > Limits** | $250 a day, $2,500 a week, $10,000 per 28 days |

Values are US dollars.

## Cap a session

```bash
agent --model claude-opus-5-5 --budget 5 -e cloud_agent_environment "Fix the failing test."
```

In the API or SDK, send `"budget": {"session": 5}`. Follow-up messages share the same budget.

A session can't be given more than $250, or less if your account sets a lower ceiling in **Agents > Settings**. A larger request fails with `budget_exceeds_ceiling`.

When a session reaches its budget, its message ends with `reason` set to `budget_hit`. Its `status` is `failed` when the agent was working and `cancelled` when it hadn't started, and the session's `error` says the same. The budget can't be raised. `conversation.prompting.blocked_reason` becomes `budget_exhausted` and new messages fail with `409`, so start a new session to continue. See [Lifecycle](/docs/sessions/lifecycle#error).

## Cap an agent

```yaml fragment
session:
  claude_code:
    model: claude-opus-5-5
  budget:
    session: 5
    day: 20
    week: 100
    month: 300
```

`session` caps each session. `day`, `week`, and `month` cap this agent's total spend over the last 1, 7, and 28 days. [Handlers](/docs/agents#handlers) take the same fields. A request that starts an agent session can send `budget.session` to replace the session cap; `day`, `week`, and `month` can't be sent in a request.

## Cap the account

Open **Billing > Limits** to set the account's 1-day, 7-day, and 28-day limits, up to $1,000, $10,000, and $40,000. The same page sets the default session budget.

Turn on **Limit spend per developer** to give each person and each API key their own limits. A person's limit covers the sessions they start from the dashboard, the CLI, and mentions. Scheduled sessions don't count toward any developer.

Only owners and admins can change these limits.

## When a limit is reached

A reached limit blocks new paid requests. Requests already running can finish, so spend can go slightly past a limit.

Budget alerts, set in **Billing > Limits**, notify you at 80% and 100% of each account limit by default. They go to the Slack [operations channel](/docs/integrations/slack#operations-channel), notification emails, and **Alerts**.

Check current limits and remaining spend with `agent budget` or `GET /v1/account/budget`.