Budgets
Cap what each session, agent, and your whole account can spend.
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
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 turn ends with reason set to budget_hit: failed when the agent was working, cancelled when it hadn't started. 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.
Cap an agent
session caps each session. day, week, and month cap this agent's total spend over the last 1, 7, and 28 days. 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, notification emails, and Settings > Alerts.
Check current limits and remaining spend with agent budget or GET /v1/account/budget.