Cap Your Spend

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. 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 and a BoxRouter API key with credentials:manage set as in Set Up Your Account.

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.

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()))

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();
}

boxrouter spend-limit set workspace --limit-usd 25 --limit-period daily

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"}'

Both fields are required, and a new cap replaces the old one. mode is the billing mode, as in 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.

import json
from boxrouter import BoxRouter

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

import { BoxRouter } from '@boxrouter/sdk';

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

boxrouter spend-limit list

curl -sSf "${BOXROUTER_BASE_URL:-https://api.boxrouter.ai/api/v1}/spend-limits" \
  -H "Authorization: Bearer $BOXROUTER_API_KEY"

Clear a Cap

Clearing succeeds if the workspace has no cap.

import json
from boxrouter import BoxRouter

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

import { BoxRouter } from '@boxrouter/sdk';

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

boxrouter spend-limit clear workspace

curl -sSf -X DELETE "${BOXROUTER_BASE_URL:-https://api.boxrouter.ai/api/v1}/spend-limits/workspace" \
  -H "Authorization: Bearer $BOXROUTER_API_KEY"

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

Buy and Manage Credits

Buy credits and top up automatically.

Check Your Limits

Quotas that are not about money.

How Sandbox Cost Works

Read what a sandbox cost.

Get Started

Sandboxes

Routing and Providers

Errors and Limits

Cost and Billing

Security and Privacy

Clients