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

# Budgets

> Cap what a machine spends, let running jobs finish at the cap, and raise a cap while work runs.

A budget caps what one machine spends. Budgets are in US dollars; prices and costs are shown in Voyager credits. A machine has no budget unless you give it one.

## A budget, and a ceiling

| | What happens |
| - | - |
| `--budget 8` | The machine pauses, with its disk kept, once it has spent $8. You're never charged more than $8. |
| `--budget 20 --ceiling 30` | At $20 new jobs are refused and running jobs finish, then the machine pauses. It always pauses by $30. |
| `--no-budget` | No cap: the machine stops only when you release it, it sits idle, or the workspace runs out of credits. |

```sh theme={"system"}
voyager cloud lease render --budget 20 --ceiling 30 --wait --yes
voyager cloud run --budget 5 --ceiling 8 --pull out/ -- python render.py
```

`lease`, `resume` and `run` take these flags. `lease` and `status` show the budget and what the machine has spent so far:

```text theme={"system"}
budget: $3.10 of $20 · stops new work at $20, pauses by $30
```

Ten minutes before a machine reaches its budget or its ceiling, its jobs carry a notice saying so. Save or copy off what matters then.

### While a machine finishes

Voyager checks spend about once a minute, so a machine stops within about one check (a few cents) of its budget, a little before it rather than after.

Once a machine reaches its budget (with a ceiling above it):

* Jobs already running keep going. File transfers and snapshots still work, so you can pull results.
* A new command is refused with `402` `BUDGET_EXCEEDED` and `details.stage` `finishing`. The message says what was spent and the command to raise the budget.
* With nothing left running, the machine pauses at once. Otherwise it pauses when its last job ends, or at the ceiling, whichever comes first.

A paused machine keeps its disk. Resume it with a larger budget to go on: `voyager cloud resume <machine> --budget 40`.

## Raise a budget

```sh theme={"system"}
voyager cloud budget <machine> --budget 40 --ceiling 60
```

This works while the machine runs, and also while it finishes its jobs at the old budget: new commands start again. A budget only goes up, never below what the machine has spent or its current cap.

## In the API

The lease body (`POST /v1/machines`) and `POST /v1/machines/{id}/resume` take `budget_usd`, `budget_ceiling_usd` and `no_budget`. Raise a running machine's budget with `POST /v1/machines/{id}/budget` and `{"budget_usd": 40, "budget_ceiling_usd": 60}`.

A machine's `billing` shows:

| Field | Meaning |
| - | - |
| `soft_cap_usd`, `soft_cap_credits` | Where new jobs stop (null without a ceiling). |
| `cap_usd`, `cap_credits` | Where it pauses: the ceiling, or the budget when there is no ceiling. |
| `budget_stage` | `finishing` once the budget is reached, else null. |
| `spent_usd` | What this allocation has spent, at its own rate. |

While it finishes, its jobs carry a `BUDGET_REACHED` notice.

## Farms and estimates

* A farm takes one budget for all its machines: see [Farm a frame range](https://docs.voyager.so/api/machines/farm.md#a-budget-for-the-whole-farm).
* To know what a Blender render will cost before you start, estimate it from a few sample frames: see [Estimate a render](https://docs.voyager.so/api/machines/blender.md#estimate-a-render).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.