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

# Budgets

> Every call is priced before it is made and refused if it would breach the cap.

Budget enforcement is structural, not a report you read the next morning. Every call is priced before it is made and refused if it would breach the cap. This is what makes it safe to leave an agent running unattended overnight.

<Note>
  An agent is **not creatable without a budget**. A null cap would mean no limit and no per-agent spend record at all.
</Note>

<Info>
  **Money is integer micro-USD on the wire.** Every amount is carried and stored as an integer number of micro-USD (`1 USD = 1,000,000` micro-USD), in fields suffixed `_micro_usd` (`cap_micro_usd`, `max_task_micro_usd`, `consumed_micro_usd`). Clients display dollars for humans but convert before sending: the CLI `--budget-usd` accepts a decimal and converts client-side, and the SDK takes whole-micro-USD strings (never a bare `number`, to avoid float rounding).
</Info>

## Creating an agent with a budget

A budget is set at agent-creation time — a period cap, a per-task ceiling, and the reset period.

<CodeGroup>
  ```bash CLI theme={"system"}
  vetta agent create --name nightly-triage --model zai-org/GLM-5.2-FP8 \
    --budget-usd 50 --max-task-usd 5 --budget-period month
  ```

  ```typescript TypeScript theme={"system"}
  const agent = await vetta.agents.create({
    name: "nightly-triage",
    model: "zai-org/GLM-5.2-FP8",
    harness: "pi",
    budget: { capMicroUsd: "50000000", maxTaskMicroUsd: "5000000", period: "month" }, // $50 / $5
  });
  ```
</CodeGroup>

Every model call or priced tool call then passes through a pre-flight gate before it is allowed to run:

```
   model / tool call
         │
         ▼
   ┌──────────────┐
   │  pre-flight  │  compute quote (upper bound at the session's window)
   │     gate     │
   └──────┬───────┘
          │  check in order:
          │   1. org balance
          │   2. agent cap_micro_usd
          │   3. task max_task_micro_usd
          │   4. session budget
          │
   pass ──┴──▶ call proceeds
   fail ─────▶ refused → budget.exceeded emitted (agent told in-band)
```

## How pre-flight pricing works

Before each model call or priced tool call, Vetta computes a **quote** — an upper bound on what the call will cost at the session's [completion window](/docs/concepts/completion-window). The quote is checked against, in order:

1. The **organization balance** — is there money? See [Credits & billing](/docs/platform/billing).
2. The **agent period cap** (`cap_micro_usd`) minus what it has already spent this period.
3. The **task ceiling** (`max_task_micro_usd`) minus what this session has already spent.
4. Any **session budget** you set explicitly.

If the quote would breach any of these, the call is refused and a `budget.exceeded` event is emitted. The agent is told, in-band, that it is out of budget, so it can wrap up cleanly rather than crash.

## Session budgets

Beyond the agent budget, a session can carry its own cap. Work pauses at the cap and resumes when you raise or remove it.

<CodeGroup>
  ```bash CLI theme={"system"}
  vetta session create --agent Refunder --budget-usd 2.00
  vetta session budget --session $SID --usd 5.00   # raise (must exceed consumed)
  ```

  ```typescript TypeScript theme={"system"}
  const session = await vetta.sessions.create({ agent: agent.id, budgetMicroUsd: "2000000" }); // $2
  await vetta.sessions.setBudget(session.id, 5_000_000);                                 // raise to $5
  ```
</CodeGroup>

Rules:

* A replacement cap must be strictly greater than the session's already-consumed cost.
* Removal is one-way: you cannot re-add a cap to a session that had one removed, or add one to a session created without it.
* Raising or removing a cap automatically resumes work that paused at it.

## Reading spend

Everything is metered against real backend cost in integer micro-USD and attributed per component and per session. Model spend is metered across the **five-tier token ledger** — `input`, `cache_write`, `cache_read`, `output`, and `reasoning` — the same tiers the [model router](/docs/concepts/model-router#what-a-model-call-costs) prices each call against.

```bash CLI theme={"system"}
vetta agent spend nightly-triage --by component
vetta session get $SID   # includes consumed_micro_usd
```

```json theme={"system"}
{ "by_component": { "model": 11902000, "computer": 481000, "search": 6474, "media": 390000 } }
```

Amounts are integer micro-USD: `11902000` is \$11.902. The `model` component decomposes into the five token tiers above; the other components are `computer`, `search` ([web tools](/docs/capabilities/tools#web-tools)) and `media` ([generation](/docs/capabilities/tools#generation-tools)). A component with no spend is absent, not zero.

## Configuration reference

An agent budget has three required fields:

<ParamField path="cap_micro_usd" type="integer" required>
  The total the agent may spend within its period, in integer micro-USD. The CLI `--budget-usd` and SDK helpers convert dollars to this before sending.
</ParamField>

<ParamField path="max_task_micro_usd" type="integer" required>
  The ceiling for a single task, in integer micro-USD. A session cannot exceed this even if the period cap has room.
</ParamField>

<ParamField path="period" type="string" required>
  The reset window: `day`, `week`, or `month`.
</ParamField>

<Card title="Next: durable runtime" icon="battery-full" href="/docs/concepts/runtime">
  Waiting costs storage, not compute.
</Card>