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

# Usage, costs and capacity

> Read Factory usage and cost estimates, and set limits for runs, spend and sandbox time.

Use **Factory → Analytics** to compare tasks, models and stages. Use the ledger when you need
usage for a run or a UTC day. Use one scope at a time: `--run` includes the run’s pinned
per-run caps; `--day` aggregates workspace usage across factories and does not return caps:

```bash theme={null}
architech factory cost --run "$RUN_ID" --json
architech factory cost --day "$(date -u +%F)" --json
```

## Read the numbers

| Metric | What it tells you |
| - | - |
| Tokens | Model usage. Two roles can use the same number of tokens and incur different costs. |
| Sandbox time | Compute time for the work, tracked separately from model usage. |
| Model and compute cost | The billed cost breakdown shown by Factory analytics. |
| API-equivalent (est.) | What the measured model usage would cost at API rates. Useful for subscription comparisons, not an invoice or an extra charge. Missing or partial estimates aren't zero usage. |

A subscription-backed run can show model usage even when no model API cost was billed. It can
still incur sandbox compute cost. Look at **By model** for the model mix and **By stage** to see
whether planning, building or reviewing used the most resources.

## Set a budget

Merge this block into your `factory.yaml` and preview the push:

```yaml theme={null}
limits:
  maxActiveRuns: 3
  maxConcurrentSandboxes: 6
  budget:
    perRunUsd: 25
    perDayUsd: 150
  sandboxHours:
    perRun: 8
    perDay: 60
```

```bash theme={null}
architech factory push --dry-run --json
```

* **Active runs:** excess work queues. Waiting for a gate is not the same as finishing a run.
* **Sandbox slots:** a full workspace sandbox cap queues a launch or wake until a slot is free.
* **Sandbox hours:** the cap includes committed time, including active reservations. A new
  reservation can be refused before all of that time is used.
* **Dollar caps:** checked against recorded spend. A run can pause after a charge takes it past
  its cap; don't treat the configured number as an exact billing cutoff.

Leave out `budget` to use the defaults ($50/run, $300/day). Once you supply `budget`, an omitted or
`null` member removes that dollar cap. This doesn't remove the time or slot limits. Runs use the
configuration version they started with, so a higher limit in a new push doesn't rewrite the cap
on an old run. See [the field reference](https://docs.mutagent.io/factory/reference/factory-yaml.md#keys).


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