Workspace spending limits

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:

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:

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:

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 for cost estimation and organization usage reporting, and Organizations & Workspaces for tenant structure.