---
title: "Budgets"
description: "Stop a run at its spending limit before the spend, per task, agent, project and team, with exit code 6 and a stored record."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.overlane.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Budgets

An alert tells you after the money is gone. A budget stops the call before it. A run asks before it spends, the answer counts the call's own estimate, and at the limit the answer is exit code 6 and a stored record.

```sh
overlane budget set --scope task --id task-12 --usd 5
overlane budget check --usd 0.40 --task task-12 --kind inference
overlane budget show
overlane budget stops
```

## Four scopes

| Scope | What it limits | Counted over |
|---|---|---|
| `task` | One task's runs | The task's whole life |
| `agent` | One agent token | The billing period |
| `project` | One project | The billing period |
| `team` | The whole workspace | The billing period |

A call is checked against every limit that applies to it. When more than one would be reached, the refusal names the tightest, the one with the least room left. With a task limit of $5 and a team limit of $50, a call that would reach the task limit is refused as a task stop.

## How a call is counted

Spent plus the call's estimate at or over a limit refuses. A run at $4.90 of a $5.00 task budget that asks for a $0.40 call is refused at call time, not after the spend.

- `budget check --record` counts an allowed estimate as spent, so the next check sees it. The budgets spend route records the actual cost afterwards.
- A spending cap set with `overlane billing caps` joins the same check, so one command covers both. See [Billing](/billing/).
- With `--meter`, the check also reads the plan allowance for reviews, CI minutes or hosted inference. A plan with no overage path refuses there, and a read-only workspace takes no new spend.
- An agent token is always checked as itself. Naming another agent does not move the spend.

## The stop is a record

Every refusal stores a row: when, which limit, what was spent, what the call was estimated at, which task, project and agent, and who asked. It holds numbers and IDs, never a prompt or a response. `overlane budget stops` lists them, newest first. Asking again with the same request ID returns the same stop and does not store a second.

```sh
overlane budget check --usd 0.40 --task task-12
# STOPPED  Stopped before the spend: the budget for task task-12 would be reached ($4.90 spent of $5.00, and this call is estimated at $0.40).
# next: overlane budget set --scope task --id task-12 --usd <higher amount>
echo $?   # 6
```

## Raising a limit is spend

Setting a first limit, or lowering one, only tightens, so any agent can do it. Raising a limit or removing it is spend above the budget, one of the safety classes (see [Autonomy](/autonomy/)). It asks for an independent agent's approval in every autonomy mode:

1. The agent runs `overlane budget set --scope task --id task-12 --usd 10` and is refused. The answer names the approval to request.
2. It requests the approval for that exact subject. Another agent, not one minted from the same token, answers with evidence.
3. The agent runs the same command with `OVERLANE_APPROVAL` set to the approval ID. An approval works once.

A person raises a limit directly, with no approval. Payments stay with a person: buying a plan, changing seats and the billing caps themselves are not reachable by an agent token.

## Agent use and the override

An agent sets a budget on the task it starts, checks before each paid call, and stops when told. A person can set, raise or remove any limit from the command line or the settings screen, and can read every stop.

Command reference: [budget show](/cli/budget-show/), [budget set](/cli/budget-set/), [budget check](/cli/budget-check/) and [budget stops](/cli/budget-stops/).

Source: https://docs.overlane.app/control-plane/budgets/index.mdx