Usage and billing

CrowNest meters sandbox runtime in compute unit seconds, converts them to credits at a server-defined rate, and enforces plan quotas and rate limits on top. The GET /v1/usage endpoint is the single source of truth for your current period, conversion rate, consumption, and quotas.

Compute unit seconds

The billing meter is compute_unit_seconds: active runtime seconds multiplied by the instance multiplier. The base multiplier is 1.0, so on the standard instance one second of runtime is one compute unit second. Metering runs from the moment a sandbox reaches ready until it's killed, expires, or fails — billing stops at expiresAt when a sandbox runs out its TTL.

Credits

Plans are denominated in credits. The conversion between compute unit seconds and credits is server-side policy, versioned by pricingVersion; the current beta default is 1 credit = 1,000 compute unit seconds.

[!IMPORTANT] Never hard-code the conversion rate. Read computeUnitSecondsPerCredit from GET /v1/usage — it can change with pricingVersion.

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.
• computeUnitSeconds.used — metered consumption this period.
• credits.used and credits.remaining — credit consumption and balance.
• quotas — your plan's current quota values.

Plans

Plan shapes are configurable beta defaults and subject to change; read quotas from GET /v1/usage for the values that apply to your organization.

Quotas vs rate limits

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

Hard quotas

A quota is an administrative bucket your plan defines; each has a numerical limit. Exceeding one returns quota_exceeded (429). Quota categories:

• max_concurrent_sandboxes
• max_sandbox_ttl_ms
• max_command_duration_ms
• Maximum upload, read, and write sizes
• Storage
• Previews per sandbox and per organization
• API requests per minute

Rate limits

The API rate limit is 120 requests per 60-second window per API key. Exceeding it returns rate_limited (429).

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.

Next steps

• API keys and scopes — the usage:read scope and per-key rate limiting.
• Sandboxes — TTL behavior and where metering starts and stops.
• Usage API reference
• SDK quickstart