Usage and billing
How sandbox-hours, dollars, plan quotas, and rate limits work in CrowNest.
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
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
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.
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.
GET /v1/usage (scope usage:read) returns:
period—start,end, andresetAtfor 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
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
Two mechanisms return HTTP 429, and they mean different things.
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_sandboxesmax_active_previews_per_org
Each bucket carries limit, and current/remaining when the value
applies org-wide.
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
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
- API keys and scopes — the
usage:readscope and per-key rate limiting. - Sandboxes — TTL behavior and where metering starts and stops.
- Usage API reference
- SDK quickstart