---
title: Workspace spending limits | Boltz API Docs
description: Cap workspace spend and use lifetime limits to enforce subtenant credit allocations.
---

A workspace spending limit is a hard, lifetime cap on billable work submitted to one workspace. Limits are denominated in **milli-USD**: `1000` is USD 1.00, so a USD 25 allocation is `25000`.

Use workspace limits when you need a budget boundary below the organization level. A common platform pattern is:

1. Create one workspace per customer or other subtenant.
2. Route every job for that subtenant to its workspace.
3. Set the workspace’s lifetime limit to the milli-USD value of the credit allocation.
4. Read the limit and accrued usage to display remaining credit in your own product.
5. Raise the absolute lifetime limit when the subtenant buys or receives more credit.

The spending limit is an enforcement mechanism, not a separate balance or payment instrument. Your organization remains responsible for the underlying Boltz charges, and an organization-level billing limit can still block work even when a workspace has headroom.

## Set a limit when creating a workspace

An admin API key can set the initial limit in the same request that creates the workspace:

Terminal window

```
curl https://api.boltz.bio/compute/v1/admin/workspaces \
  -X POST \
  -H "x-api-key: $BOLTZ_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Customer A",
    "spending_limit": {
      "type": "lifetime",
      "limit": {
        "amount": 25000,
        "currency": "MILLI_USD"
      }
    }
  }'
```

Only `type: "lifetime"` and `currency: "MILLI_USD"` are currently supported.

## Set or change an existing limit

Use the workspace spending-limit endpoint with an admin API key:

Terminal window

```
curl "https://api.boltz.bio/compute/v1/admin/workspaces/$WORKSPACE_ID/spending-limit" \
  -X PUT \
  -H "x-api-key: $BOLTZ_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "type": "lifetime",
    "limit": {
      "amount": 50000,
      "currency": "MILLI_USD"
    }
  }'
```

The amount is the workspace’s **absolute lifetime ceiling**, not the size of a top-up. For example, if the current limit is `25000` and you grant another USD 25, set the new limit to `50000`.

You can raise or lower a limit, but the API rejects a new value below the workspace’s accrued usage plus spend already reserved by active work. There is no endpoint to remove a configured limit or reset its ledger. For recurring allocations, keep the lifetime ledger and increase its absolute ceiling at the start of each new period.

## Read usage against the limit

Admin keys can read any workspace in their organization. A workspace key can read the limit for its assigned workspace:

Terminal window

```
curl "https://api.boltz.bio/compute/v1/admin/workspaces/$WORKSPACE_ID/spending-limit" \
  -H "x-api-key: $BOLTZ_API_KEY"
```

A configured limit returns:

```
{
  "type": "lifetime",
  "limit": {
    "amount": 50000,
    "currency": "MILLI_USD"
  },
  "accrued_usage": {
    "amount": 18400,
    "currency": "MILLI_USD"
  }
}
```

If no workspace limit is configured, the endpoint returns `null` and work continues to use organization-level billing without a workspace cap.

`accrued_usage` is the billable usage recorded by the workspace limit ledger. Tracking starts when the limit is first configured, so earlier usage is not backfilled. Active work may also have reserved spend that is enforced against the limit but is not included in `accrued_usage`.

Compute displayed headroom as `limit.amount - accrued_usage.amount`, but treat it as an upper bound while work is active because reservations also consume headroom. The API remains the authority on whether a new job fits.

## What happens at the limit

Before billable work starts, Boltz reserves its estimated cost against both the organization and workspace ledgers. A request that does not fit the remaining workspace headroom is rejected with the error code `workspace_spending_limit_reached`. Concurrent submissions cannot collectively reserve more than the cap.

Setting a limit to zero blocks new billable work. Work with zero cost, including supported test-mode behavior, does not consume the limit.

## Model subtenant credits

Keep the commercial credit balance in your platform and use the Boltz workspace limit as its compute-spend guardrail:

| Platform concern       | Recommended mapping                                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Tenant isolation       | One Boltz workspace per subtenant                                                                                 |
| Credit grant           | Convert the grant to milli-USD and raise the workspace’s absolute lifetime limit                                  |
| Job attribution        | Submit with the subtenant’s workspace key, or use an admin key with `workspace_id`                                |
| Balance display        | Read `limit` and `accrued_usage`; show that available credit is approximate while jobs are active                 |
| Organization reporting | Query `GET /compute/v1/admin/usage` grouped by `workspace_id`                                                     |
| Revoking future spend  | Stop submitting work and lower the limit; retry after active reservations settle if the API rejects the new floor |

If your product’s credits do not map one-to-one to USD, perform that conversion in your platform. Boltz spending limits always use milli-USD and do not store your customer-facing credit unit.

See [Costs](/docs/guides/costs/index.md) for cost estimation and organization usage reporting, and [Organizations & Workspaces](/docs/guides/organizations-and-workspaces/index.md) for tenant structure.