Rate Limits
Per-key request quotas and how to handle 429 responses.
Requests are rate limited per account — the limit is keyed to the API key's owner, so all keys belonging to the same user draw from one shared quota. Limits are grouped by operation class, so read traffic and write traffic are metered independently.
Limits
| Class | Limit | Applies to |
|---|---|---|
| Read | 120 req/min | List/read agents, list AI models, list/read sources, list/read conversations, list webhook endpoints. |
| Write | 60 req/min | Create/update/delete agents and conversations, visitor/human send, action‑result, webhook create/delete, delete sources. |
| Training | 20 req/min | Create sources, retrain sources, start crawls. |
| Polling | 200 req/min | Poll crawl results, training‑job status, and conversation messages. |
The high polling allowance is deliberate: training, crawls, and AI replies are asynchronous, so you are expected to poll those endpoints frequently. Keep ingestion (training) calls well under the 20/min ceiling.
Which limit applies to each endpoint
| Endpoint | Method | Class |
|---|---|---|
/ai-models | GET | Read |
/organizations/{org}/agents | GET | Read |
/organizations/{org}/agents | POST | Write |
/agents/{agent} | GET | Read |
/agents/{agent} | PATCH | Write |
/agents/{agent} | DELETE | Write |
/agents/{agent}/sources | GET | Read |
/agents/{agent}/sources/{source} | GET | Read |
/agents/{agent}/sources | POST | Training |
/agents/{agent}/sources/{source}/retrain | POST | Training |
/agents/{agent}/sources/{source} | DELETE | Write |
/agents/{agent}/training-jobs/{taskId} | GET | Polling |
/organizations/{org}/crawls | POST | Training |
/organizations/{org}/crawls/{taskId} | GET | Polling |
/agents/{agent}/conversations | GET | Read |
/agents/{agent}/conversations | POST | Write |
/agents/{agent}/conversations/{conversation} | GET | Read |
/agents/{agent}/conversations/{conversation} | PATCH | Write |
/agents/{agent}/conversations/{conversation} | DELETE | Write |
/agents/{agent}/conversations/{conversation}/messages | GET | Polling |
/agents/{agent}/conversations/{conversation}/messages | POST | Write |
/agents/{agent}/conversations/{conversation}/human-messages | POST | Write |
/agents/{agent}/conversations/{conversation}/messages/{message}/action-result | POST | Write |
/agents/{agent}/webhook-endpoints | GET | Read |
/agents/{agent}/webhook-endpoints | POST | Write |
/agents/{agent}/webhook-endpoints/{endpoint} | DELETE | Write |
When you exceed a limit
Exceeding a limit returns 429 Too Many Requests. The response includes standard rate‑limit
headers:
| Header | Meaning |
|---|---|
Retry-After | Seconds to wait before retrying. |
X-RateLimit-Limit | Maximum requests allowed in the window. |
X-RateLimit-Remaining | Requests remaining in the current window. |
Back off when you receive a 429. Respect Retry-After and use exponential backoff with jitter
for retries rather than tight retry loops.