---
title: Costs | Boltz API Docs
description: Estimate what a run will cost before you submit it, understand how billing works, and develop for free in test mode.
---

Runs are billed by the amount of compute they use, measured at run time. Before you submit, you can ask the API for a cost estimate — and while you're building an integration, you can run end-to-end for free in [test mode](/docs/guides/test-environment/index.md).

## Estimate a cost before running

Every job type has an `estimate-cost` endpoint that returns an estimate **without creating a run or using any GPU**:

- [`POST /compute/v1/predictions/structure-and-binding/estimate-cost`](https://api.boltz.bio/docs/api/resources/predictions/subresources/structure_and_binding/methods/estimate_cost/)
- [`POST /compute/v1/predictions/adme/estimate-cost`](https://api.boltz.bio/docs/api/resources/predictions/subresources/adme/methods/estimate_cost/)
- [`POST /compute/v1/protein/design/estimate-cost`](https://api.boltz.bio/docs/api/resources/protein/subresources/design/methods/estimate_cost/)
- [`POST /compute/v1/protein/library-screen/estimate-cost`](https://api.boltz.bio/docs/api/resources/protein/subresources/library_screen/methods/estimate_cost/)
- [`POST /compute/v1/small-molecule/design/estimate-cost`](https://api.boltz.bio/docs/api/resources/small_molecule/subresources/design/methods/estimate_cost/)
- [`POST /compute/v1/small-molecule/library-screen/estimate-cost`](https://api.boltz.bio/docs/api/resources/small_molecule/subresources/library_screen/methods/estimate_cost/)

The CLI exposes the same estimate commands:

| Job type                         | CLI command                                                                                                                                     |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Structure and binding prediction | `boltz-api predictions:structure-and-binding estimate-cost`                                                                                     |
| ADME prediction                  | [`boltz-api predictions:adme estimate-cost`](https://api.boltz.bio/docs/api/cli/resources/predictions/subresources/adme/methods/estimate_cost/) |
| Protein design                   | `boltz-api protein:design estimate-cost`                                                                                                        |
| Protein library screen           | `boltz-api protein:library-screen estimate-cost`                                                                                                |
| Small-molecule design            | `boltz-api small-molecule:design estimate-cost`                                                                                                 |
| Small-molecule library screen    | `boltz-api small-molecule:library-screen estimate-cost`                                                                                         |

Pass the same input you'd use to start the run:

```
est = client.small_molecule.design.estimate_cost(
    target={"entities": [{"type": "protein", "value": "...", "chain_ids": ["A"]}]},
    num_molecules=100,
)
print(est.estimated_cost_usd)        # e.g. "0.5000"
print(est.breakdown.num_units)       # 100
```

The response encodes money as **decimal strings in USD** (to preserve precision):

```
{
  "estimated_cost_usd": "0.5000",
  "breakdown": {
    "application": "small_molecule_design",
    "num_units": 100,
    "cost_per_unit_usd": "0.0050"
  },
  "disclaimer": "This is an estimate only and may differ from your actual charges."
}
```

`estimated_cost_usd` is the authoritative total. `num_units` is what you requested — samples for structure-and-binding, molecules or proteins for design and screens. `cost_per_unit_usd` is a rounded per-unit figure and may bundle overhead, so it won't always multiply out exactly to the total.

The numbers above are an illustrative format, not a price quote. The estimate is approximate — **final billing is based on the exact compute measured at run time**, and for large library screens the estimate is extrapolated from a sample, so it's less precise for highly variable inputs.

## Develop for free in test mode

A **test-mode API key** (`mode: "test"`, prefix `sk_bc_*_test_`) runs the full request → poll → fetch-results lifecycle against the real endpoints but returns **synthetic results with no GPU usage and no billing**. Use it to build and test your integration for free, then switch to a live key for real runs. See [Test environment](/docs/guides/test-environment/index.md) and [key prefixes](/docs/guides/authentication#key-prefixes/index.md).

## Track usage and cap spend

Retrieve aggregated usage with [`admin.usage.list`](https://api.boltz.bio/docs/api/resources/admin/subresources/usage/methods/list/) (`GET /compute/v1/admin/usage`, admin key required). You give a time range and `window_size` (`HOUR` or `DAY`) and optionally group by workspace or application:

```
for bucket in client.admin.usage.list(
    starting_at="2026-05-01T00:00:00Z",
    ending_at="2026-05-31T00:00:00Z",
    window_size="DAY",
    group_by="workspace_id",
):
    print(bucket.start_time, bucket.workspace_id, bucket.quantity)
```

Each bucket's `quantity` is the aggregated **billed unit count** for that window (not a dollar amount).

To cap spend, set a per-workspace **spending limit** (a lifetime cap, denominated in milli-USD) on the workspace's admin endpoint. Workspaces with no limit set bill against the organization. See [Organizations & workspaces](/docs/guides/organizations-and-workspaces/index.md).