Rate limits and other limits

API rate limits

• Windows are fixed, aligned on the minute.
• Over the limit, the API answers 429 with Retry-After (seconds until the window ends) and {"detail": "rate limit exceeded", "code": "rate_limited"}.
• Failed authentications are counted per client IP address, apart from everything else. Over 30 in a minute, requests from that IP with an invalid key get 429 until the minute ends. Requests with a valid key from the same IP are not affected: they only count against their key's own limit. A CI job with a wrong key cannot lock out the other jobs behind the same NAT.

Handle 429 by waiting Retry-After seconds and retrying. The CLI does it for you.

To stay far below the limit: poll a run every 10 to 30 seconds (not every second), use webhooks for long runs, and use after_seq when following a call trace.

Pagination

List endpoints that can grow return a page:

{ "count": 1234, "limit": 50, "offset": 0, "items": [ ] }

limit is capped at 200. Items are newest first, except events (by seq). Iterate with offset until offset >= count.

Scenarios, targets, tags, environments, members, variants, webhooks, alert channels, plans and API keys are returned as plain lists.

CI wait

POST /scenarios/{id}/runs?wait=true holds the request for at most 900 seconds (timeout, default 600). The server waits asynchronously (it checks the run every 2 seconds without holding a worker or a database connection), so long waits are fine on our side; proxies on your side may still cut long requests. See CI/CD.

Sending a test alert (POST /alert-channels/{id}/test) is limited to 5 per minute per channel.

Plan limits

Calls over the concurrency or hourly limits wait in the queue; they are not refused. GET /me returns your plan's limits (plan.max_concurrent_calls, plan.max_seats, plan.max_countries, plan.included_calls_per_month).

Scenario limits

From the grammar:

Other sizes: scenario name 200 characters, tag name 40, version label 60, API key name 80, target name 120.