Skip to main content

Current limits

Every request counts against a per-key bucket of 300 requests per minute. Endpoints that cost more to run have their own, lower bucket on top of that, counted separately for each API key. Each operation in the API reference belongs to one of these buckets. An operation that is not listed above uses the default.

Response headers

Operations that have their own bucket (the table above, every row except the default) return the state of that bucket on every response: Plain reads that only use the 300 per minute default do not return X-RateLimit-* headers. Do not rely on the headers being present on every response; use them when they are there and Retry-After when you get a 429.

Handling 429s

A 429 response has the same shape whichever limit you hit: a detail field with a complete sentence, and a Retry-After header. (Some older responses also repeat the sentence in an error field; read detail.)
  1. Read the Retry-After header
  2. Wait that many seconds before retrying
  3. Use exponential backoff for sustained high-volume workloads
A 429 is never stored by idempotency: retrying a write with the same Idempotency-Key after the wait runs it again.

Tips for staying under limits

  • Paginate efficiently: use page, limit and the cursor parameters described in Pagination instead of fetching everything at once
  • Batch lead enrollment: use lead_list_id instead of individual lead_ids arrays
  • Cache read responses: analytics and agent configs change infrequently
  • Webhook over polling: register webhook endpoints instead of polling the jobs or conversations API