Spend budgets
Limits on what agents spend per task, per project and per organization — what happens at a limit, which policy layer sets which limit, and what a budget cannot see.
Budgets are part of the execution policy. Set them in Settings → Execution policy → Spend budget, or in the policy JSON:
{
"budget": {
"organizationMonthlyUsd": 500,
"projectMonthlyUsd": 100,
"taskUsd": 5,
"taskTokens": 2000000,
"warnAt": 0.8
}
}| Limit | Covers |
|---|---|
taskUsd, taskTokens | One task over its whole life (tokens: input plus output) |
projectMonthlyUsd | Each project, per calendar month (UTC) |
organizationMonthlyUsd | All projects together, per calendar month (UTC) |
null or an empty field means no limit, which is the default.
At a limit
- A running task stops before its next agent session and goes to
RECOVERY_REQUIRED, with the limit and the spend as the reason. Raise the limit, then press Retry: the task continues from its checkpoint. - A task that is being verified is not stopped. Verification costs nothing and may complete the task. If verification fails, the task stops instead of starting a fix.
- Queued tasks do not start, and their status says why. They start by themselves when the limit is raised or the month ends.
- Owners and administrators get one notice per month when a monthly limit passes
warnAt(80 % by default) and one when it is reached — in the app, by email, and in chat channels that take budget notices.
Which layer sets which limit
| Limit | Read from |
|---|---|
| Organization | Platform and organization policy only. A project or task cannot raise it. |
| Project | Platform, organization and project policy |
| Task | Any layer. A task's own policy can lower the limits, never raise them. |
See the spend
The dashboard's overview and Settings show this month's spend against the limits.
GET /api/v1/orgs/:orgId/budget returns the same figures, and each task carries its own spend in usage.
What a budget cannot see
Spend is what the agent or provider reports when a session ends, so one session can overshoot a limit; the task
stops before the next one. Agents that report tokens but no cost are not covered by a dollar limit: use
taskTokens for them. When a project or organization limit is reached, other running tasks stop when they next
report spend or ask for another session, not at the same instant.