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

# Cap Your Spend

> Cap what a workspace can spend on BoxRouter-billed sandboxes.

Set one cap on what a workspace can spend on BoxRouter-billed sandboxes. Sandboxes that use your own provider keys do not count.

The cap counts settled charges and open [reservations](https://boxrouter.ai/docs/cost.md#funding-from-your-balance). BoxRouter refuses to create or extend a sandbox if the new reservation would exceed it. A sandbox that is already running keeps running.

**Before You Begin:** A [client](https://boxrouter.ai/docs/quickstart.md) and a BoxRouter API key with `credentials:manage` set as in [Set Up Your Account](https://boxrouter.ai/docs/setup.md).

## Set the Cap

Set the cap through a client, the CLI, or the API. The dashboard does not edit it yet. Execution-only keys get `403`. `workspace` is the only scope; any other scope fails with `400`.

```python Python theme={"theme":"css-variables"}
import json
from boxrouter import BoxRouter

with BoxRouter() as client:
    cap = client.spend_limits.set("workspace", limit_usd="25", limit_period="daily")
    print(json.dumps(cap.to_dict()))
```

```typescript TypeScript theme={"theme":"css-variables"}
import { BoxRouter } from '@boxrouter/sdk';

const client = new BoxRouter();
try {
  const cap = await client.spendLimits.set('workspace', { limit_usd: '25', limit_period: 'daily' });
  console.log(JSON.stringify(cap));
} finally {
  await client.close();
}
```

```bash CLI theme={"theme":"css-variables"}
boxrouter spend-limit set workspace --limit-usd 25 --limit-period daily
```

```bash HTTP theme={"theme":"css-variables"}
curl -sSf -X PUT "${BOXROUTER_BASE_URL:-https://api.boxrouter.ai/api/v1}/spend-limits/workspace" \
  -H "Authorization: Bearer $BOXROUTER_API_KEY" -H "Content-Type: application/json" \
  -d '{"limit_usd": "25", "limit_period": "daily"}'
```

Output

```json theme={"theme":"css-variables"}
{"mode": "test", "scope": "workspace", "spend_limit": {"limit_usd": "25", "limit_period": "daily"}}
```

Both fields are required, and a new cap replaces the old one. `mode` is the billing mode, as in [Check Your Balance](https://boxrouter.ai/docs/credits.md#check-your-balance). `limit_period` sets when the cap resets:

| `limit_period` | Resets |
| - | - |
| `daily` | 00:00 UTC |
| `monthly` | The first of the month, UTC |
| `total` | Never |

## Read the Cap

`GET /spend-limits` returns the cap, or `null` when none is set, and how much of it the current period has used.

```python Python theme={"theme":"css-variables"}
import json
from boxrouter import BoxRouter

with BoxRouter() as client:
    print(json.dumps(client.spend_limits.list().to_dict()))
```

```typescript TypeScript theme={"theme":"css-variables"}
import { BoxRouter } from '@boxrouter/sdk';

const client = new BoxRouter();
try {
  console.log(JSON.stringify(await client.spendLimits.list()));
} finally {
  await client.close();
}
```

```bash CLI theme={"theme":"css-variables"}
boxrouter spend-limit list
```

```bash HTTP theme={"theme":"css-variables"}
curl -sSf "${BOXROUTER_BASE_URL:-https://api.boxrouter.ai/api/v1}/spend-limits" \
  -H "Authorization: Bearer $BOXROUTER_API_KEY"
```

Output

```json theme={"theme":"css-variables"}
{"mode": "test", "workspace": {"limit_usd": "25", "limit_period": "daily"}, "workspace_spent_nanodollars": "0"}
```

## Clear a Cap

Clearing succeeds if the workspace has no cap.

```python Python theme={"theme":"css-variables"}
import json
from boxrouter import BoxRouter

with BoxRouter() as client:
    print(json.dumps(client.spend_limits.clear("workspace").to_dict()))
```

```typescript TypeScript theme={"theme":"css-variables"}
import { BoxRouter } from '@boxrouter/sdk';

const client = new BoxRouter();
try {
  console.log(JSON.stringify(await client.spendLimits.clear('workspace')));
} finally {
  await client.close();
}
```

```bash CLI theme={"theme":"css-variables"}
boxrouter spend-limit clear workspace
```

```bash HTTP theme={"theme":"css-variables"}
curl -sSf -X DELETE "${BOXROUTER_BASE_URL:-https://api.boxrouter.ai/api/v1}/spend-limits/workspace" \
  -H "Authorization: Bearer $BOXROUTER_API_KEY"
```

Output

```json theme={"theme":"css-variables"}
{"mode": "test", "scope": "workspace", "spend_limit": null}
```

## When the Cap Is Reached

Creating or extending the sandbox fails with `402 spend_limit_exceeded`. Its `details` name the `scope` (`workspace`), the `period`, and the limit, spent, and requested amounts in nanodollars.
To continue, set the cap again with a higher `limit_usd`, or clear it.

At a daily or monthly boundary, settled spending from the previous period stops counting; open reservations still count.

## Next Steps

> [card] [Buy and Manage Credits](https://boxrouter.ai/docs/credits.md)
>
> Buy credits and top up automatically.

> [card] [Check Your Limits](https://boxrouter.ai/docs/limits.md)
>
> Quotas that are not about money.

> [card] [How Sandbox Cost Works](https://boxrouter.ai/docs/cost.md)
>
> Read what a sandbox cost.


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