# What is a spending limit?

A spending limit is a cap on how much a key, a job or a machine may cost, enforced before the money is spent rather than billed after.

**Runtime stacks four of them, and the outermost means you can never owe
money.** Credit is prepaid, so a bill cannot pass your balance; each key can
carry a daily limit; each create can carry a price ceiling; and each sandbox
can carry a lifetime ceiling ([security](/docs/security#read-only-keys-and-daily-limits)).
A refused request charges nothing.

## Why it matters for AI agents

An agent that loops can start a machine per iteration, forget to stop them, or
retry a failing step all night. A human would notice by morning; a budget alert
would notice after the money is gone. A limit checked at the moment of each
request stops the next create instead, and leaves the agent a clear error to
act on. This matters most for agents that run unattended: overnight evals, CI,
and agents that other people's prompts can steer.

## The four layers on Runtime

| Layer                | Scope                         | What happens at the cap                                                           |
| -------------------- | ----------------------------- | --------------------------------------------------------------------------------- |
| Prepaid balance      | The account                   | Charges stop at zero; you never owe money                                         |
| Daily spending limit | One key's agent, any 24 hours | Create, wake, extension or renewal fails with `spending_limit_reached` (HTTP 402) |
| `maxCostMicros`      | One create                    | The create is refused if its first lease would cost more                          |
| `maxTotalCostMicros` | One sandbox, its whole life   | The most the sandbox may cost from start to end                                   |

The daily limit counts settled charges plus money still on hold, including
renewals and parked storage, and room returns as older spending leaves the
window. A running sandbox keeps its current lease when the limit is reached.
Set the limit above what the agent's paused sandboxes cost in a day: paused
storage that cannot be paid for is treated like storage on an empty balance,
with a notice and seven days before deletion.

Amounts are in microdollars, millionths of a dollar: `5_000_000` is $5.

## Cap one sandbox

```ts check
import { RuntimeError, Sandbox } from "withruntime";

try {
  await using sbx = await Sandbox.create({
    funding: "paid",
    maxCostMicros: 200_000, // refuse if the first lease would pass $0.20
    maxTotalCostMicros: 5_000_000, // at most $5 over its life
  });
  console.log((await sbx.exec("echo ok")).stdout);
} catch (error) {
  if (error instanceof RuntimeError && error.code === "spending_limit_reached")
    console.log("over this key's daily limit; stop and ask");
  else throw error;
}
```

```python check
from withruntime import Runtime, RuntimeError

runtime = Runtime()
try:
    with runtime.sandboxes.create(
        funding="paid", max_cost_micros=200_000, max_total_cost_micros=5_000_000
    ) as sbx:
        print(sbx.exec("echo ok").stdout)
except RuntimeError as error:
    if error.code != "spending_limit_reached":
        raise
    print("over this key's daily limit; stop and ask")
```

The SDKs do not retry `spending_limit_reached`. An agent that meets it should
stop and tell the person it works for.

## What a limit costs you in room

For scale, a 2 vCPU, 4 GiB sandbox costs $0.03125 an hour waiting on a model
and $0.08 an hour with both CPUs busy, so a $25 daily limit covers about 312
fully busy sandbox-hours a day at that size ([pricing](/docs/pricing)).

## Who can set one

A key's daily limit is set, changed or removed only on the website at API
keys, by the member who made the key or by an owner or admin. No key can
raise, remove or set a limit, and every change is in the audit log.

## Related

- [What are least-privilege API keys?](/glossary/least-privilege-api-keys)
- [What is a CPU floor?](/glossary/cpu-floor)
- [Pricing](/docs/pricing)
- [Sandbox cost calculator](/calculators/sandbox-cost-calculator)

Facts on this page were checked on 25 September 2026.