Guides

Rate limits

Understand the request limits applied to your API key.

Every API key is rate-limited on a per-endpoint, per-hour basis. Limits are generous for typical usage but exist to protect the platform from abuse.

Default limits

Endpoint groupLimit
POST /v1/tools/* (all generation endpoints)500 requests/hour
GET /v1/tools/executions/{id}5,000 requests/hour
POST /v1/tools/executions/{id}/cancel250 requests/hour
GET /v1/files, GET /v1/files/{id}50,000 requests/hour
POST /v1/files/{id}/hydrate2,500 requests/hour
POST /v1/files/upload500 requests/hour
POST /v1/files/search500 requests/hour
GET /v1/resources/*2,500 requests/hour
GET /v1/webhooks/endpoints500 requests/hour
POST /v1/webhooks/endpoints10 requests/hour
DELETE /v1/webhooks/endpoints/{id}10 requests/hour

These limits apply per API key. If you need higher limits for your use case, contact us at [email protected].

Response headers

Every response includes rate limit headers:

HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp (seconds) when the window resets

Handling 429 responses

When you exceed the limit, the API returns 429 Too Many Requests.

Best practices:

  • Back off exponentially. Wait 1s, then 2s, then 4s, etc.
  • Use webhooks instead of polling. If you’re hitting limits on GET /v1/tools/executions/{id}, switch to webhooks so you don’t need to poll at all.
  • Cache resource lists. Avatar presenters and TTS voices change infrequently. Cache the response and refresh every few hours rather than on every request.