Rate limits
Every account starts at 10 requests per second with a burst of 20. Higher limits are granted per account — ask, and tell us the shape of your traffic.
What counts
Every authenticated /v1 request: submitting a job, polling it,
downloading HTML, reading your balance. Polling is not free, which is the
main thing to design around.
The limit is applied per account, not per key. Issuing ten keys to ten machines does not give you ten times the limit — they share one allowance.
How the limit behaves
A token bucket, not a fixed window. The bucket holds up to
burst tokens and refills continuously at
rps per second. Each request spends one.
- Idle for a while, then send 20 at once: all 20 go through.
- Sustained traffic settles at exactly your
rps. - There is no window boundary to game — and no boundary that lets twice your limit through back to back, which is what a fixed window does.
Headers
| Header | On | Meaning |
|---|---|---|
X-RateLimit-Limit | every response | Your sustained requests per second |
X-RateLimit-Remaining | every response | Whole tokens left in the bucket |
Retry-After | 429 only | Seconds until one token exists |
Being limited
HTTP/1.1 429 Too Many Requests
Retry-After: 2
{"ok": false, "code": "rate_limited", "limitRps": 10,
"retryAfterSeconds": 2,
"error": "Rate limit exceeded: 10 request/second for this account…"}Retry-After. It is rounded up to the
next whole second, so a client that waits exactly that long never comes
back early and never burns a second rejection. Retrying immediately in a
loop is how an account spends its whole allowance on rejections.
Designing inside the limit
- Batch. 1,000 URLs in one job is one request. A thousand single-URL jobs is a thousand.
- Poll the job, not each task. One job poll returns every task's status.
- Poll every 3–5 seconds. A page takes about 13 seconds to render; polling every 200 ms learns nothing new and costs 25× more.
- Back off on 429 and 503. Both carry
Retry-After.
At 10/s a single client can comfortably run a 1,000-URL job and poll it every 3 seconds while downloading results in parallel. If you are hitting the limit with that pattern, something is retrying in a loop.
Getting a higher limit
Limits are set per account by an operator. Tell us your peak requests per second, whether it is steady or bursty, and the volume of pages per day — the limit is then set from the shape of the traffic rather than guessed.