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

# Budgets

> Every meter, window and scope a budget can use, what happens when one runs out, and how a person tops it up

# Budgets

Budgets are set in `governance_config["budgets"]`, one list of limits per
scope. Each limit caps one **meter** over one **window**.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
agent_config = {
    "governance_config": {
        "enabled": True,
        "profile": "interactive-dev",
        "budgets": {
            "application_id": "support-desk",
            "application": [{"meter": "model_cost_usd", "limit": 20.0, "window": "day"}],
            "request": [
                {"meter": "model_cost_usd", "limit": 0.50},
                {"meter": "tool_calls", "limit": 40, "on_exhausted": "terminate"},
            ],
        },
    }
}
```

## Scopes

| Scope         | Counts                                                                                                |
| ------------- | ----------------------------------------------------------------------------------------------------- |
| `request`     | One run, from `run()` to its end, resumes included. The same limit applies to every run of the agent. |
| `session`     | Every run with the same `session_id`.                                                                 |
| `agent`       | Every run of this agent.                                                                              |
| `application` | Every agent that names the same `application_id` (required for this scope).                           |

Scopes: `request`, `session`, `agent`, `application`.

## Meters

| Meter             | Counts                                                                                                                 |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `model_cost_usd`  | Dollars spent on model calls, priced from the provider's published rates. Each call's price is held before it is made. |
| `model_tokens`    | Tokens in and out of model calls.                                                                                      |
| `model_calls`     | Model calls.                                                                                                           |
| `tool_calls`      | Tool calls, counted as each is authorized.                                                                             |
| `sandbox_seconds` | Seconds sandbox sessions were open.                                                                                    |
| `subagent_runs`   | Workers started with spawn\_subagents.                                                                                 |

A model call's price is held before the call: the input it counts, and the output at `model_config["max_tokens"]`, or 4096 tokens (sent to the provider as the call's ceiling) when none is set.

## Windows

| Window  | Resets                                                               |
| ------- | -------------------------------------------------------------------- |
| `total` | Never resets: the whole life of the scope (a request, a session...). |
| `day`   | Resets at 00:00 UTC.                                                 |
| `month` | Resets on the first of the month, 00:00 UTC.                         |

## A limit

| Field          | Default   |                                                                                     |
| -------------- | --------- | ----------------------------------------------------------------------------------- |
| `meter`        | required  | One of the meters above.                                                            |
| `limit`        | required  | Greater than zero, in the meter's unit.                                             |
| `window`       | `"total"` | One of the windows above.                                                           |
| `warn_at`      | `0.8`     | The fraction of the limit that records a warning in the trace.                      |
| `on_exhausted` | `"pause"` | `pause`: the run waits for a person (`awaiting_budget`). `terminate`: the run ends. |

What one meter may reach in one scope, and what happens at the wall.

## When a budget runs out

A run that would go over a `pause` limit stops **before** the call and returns
`status: "awaiting_budget"` with `budget_request`: the budget, what is spent, what
the call needs, and the shortfall. Then:

* `await agent.grant_budget(run_id, approver=..., amount=...)` adds to that budget
  (without `amount`, just the shortfall of the call that stopped), recorded with
  the approver's name; then `await agent.resume(run_id)`.
* `await agent.deny_budget(run_id, approver=...)` ends the run instead.
* `await agent.budget_status(run_id)` shows each budget's `limit`, `granted`,
  `spent`, `reserved` and `remaining`.

Over HTTP: `GET /runs/{run_id}/budget` (the budgets and the run's `requests`) and
`POST /runs/{run_id}/budget`. The design is in
[durable runs](/docs/core-concepts/durable-runs).