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. |
| Write | 60 req/min | Update & delete agents, delete sources. |
| Training | 20 req/min | Create sources, retrain sources, start crawls. |
| Polling | 200 req/min | Poll crawl results and training‑job status. |
The high polling allowance is deliberate: training and crawl jobs are asynchronous, so you are expected to poll their status 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 |
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.