# Usage and billing (/docs/concepts/usage-and-billing)



CrowNest meters sandbox runtime per second, shows usage as sandbox-hours and
dollars, and enforces plan quotas and rate limits on top. The `GET /v1/usage`
endpoint is the single source of truth for your current period, pricing metadata,
consumption, and quotas.

## Compute unit seconds [#compute-unit-seconds]

The billing meter is `compute_unit_seconds`: active sandbox runtime
rounded up to the next whole second, where one second of runtime is one
compute unit second. Metering runs from sandbox creation until it's
killed, expires, or fails — billing stops at `expiresAt` when a sandbox
runs out its TTL.

## Dollars and Free credit [#dollars-and-free-credit]

The standard runtime launch rate is $0.12 per sandbox-hour, billed to the
second. Free organizations receive a one-time $10 Free credit balance. Paid
Builder and Scale plans include monthly usage and then continue as metered
overage.

<Callout type="warn" title="Important">
  Never hard-code the conversion rate. Read `computeUnitSecondsPerCredit`,
  `currencyPerCredit`, and `pricingVersion` from `GET /v1/usage`; the server pins those
  values for the organization's active pricing version.
</Callout>

`GET /v1/usage` (scope `usage:read`) returns:

* `period` — `start`, `end`, and `resetAt` for the current billing period.
* `pricingVersion` — the pricing policy in effect.
* `computeUnitSecondsPerCredit` — the current conversion rate.
* `currencyPerCredit` — the dollar value used with the conversion rate.
* `computeUnitSeconds.used` — metered consumption this period.
* `credits.used` — compatibility field for server-rated usage.
* `credits.remaining` — Free credit remaining when your plan has a capped balance.
* `quotas` — your plan's current quota values.

## Plans [#plans]

These are launch defaults. Read `quotas` from `GET /v1/usage` for the values
that apply to your organization.

| Plan       | Included usage      | Concurrent sandboxes | Session ceiling | Artifact retention |
| ---------- | ------------------- | -------------------: | --------------: | -----------------: |
| Free       | One-time $10 credit |                    2 |             1 h |             7 days |
| Builder    | $20 / month         |                   25 |            24 h |            30 days |
| Scale      | $100 / month        |                  100 |            72 h |            90 days |
| Enterprise | Custom              |                  250 |          7 days |           365 days |

## Quotas vs rate limits [#quotas-vs-rate-limits]

Two mechanisms return HTTP 429, and they mean different things.

### Hard quotas [#hard-quotas]

A quota is an administrative bucket with a numerical limit. Exceeding one
returns `quota_exceeded` (429). `GET /v1/usage` reports these quota buckets
in `quotas`:

* `max_concurrent_sandboxes`
* `max_active_previews_per_org`

Each bucket carries `limit`, and `current`/`remaining` when the value
applies org-wide.

### Rate limits [#rate-limits]

The API rate limit is 120 requests per 60-second window per API key and
route family. Exceeding it returns `rate_limited` (429), with a `resetAt`
in the error details.

### Telling them apart [#telling-them-apart]

Both arrive as 429, so branch on the error code:

* `quota_exceeded` — a plan quota is exhausted. Free capacity (for
  example, kill idle sandboxes) or upgrade; retrying immediately won't
  help.
* `rate_limited` — you're sending requests too fast. Back off and retry
  after the window passes.

A related code is `sandbox_ttl_exceeded` (400), returned when a create
request asks for a `ttlMs` above your plan's ceiling.

Two billing-specific codes can also block new sandbox creates:

* `credit_exhausted` — the Free credit balance is exhausted. Existing running
  sandboxes continue until their TTL; create a paid subscription or contact
  support to start more sandboxes.
* `billing_spend_cap_reached` — a paid organization's monthly spend cap is
  reached. Existing running sandboxes continue; raise or clear the cap from
  Billing to start more.

## Next steps [#next-steps]

* [API keys and scopes](/docs/concepts/api-keys) — the `usage:read` scope
  and per-key rate limiting.
* [Sandboxes](/docs/concepts/sandboxes) — TTL behavior and where metering
  starts and stops.
* [Usage API reference](/docs/api/projects-and-usage)
* [SDK quickstart](/docs/quickstart/sdk)