Rate limits

Rate limits are enforced per API key using a token-bucket algorithm. Bursts are allowed up to capacity, sustained use is limited by rate.

Limits

"All other reads" covers search-status, search-history, results-by-domain, unique-emails, credits, and stats.

How token buckets work

You start with the full capacity of tokens. Every call spends one. Tokens refill at rate per minute. When the bucket is empty, you get 429 Too Many Requests.

Example: at 30/min for find-email with capacity 60, you can fire 60 requests instantly. Then you refill at one request every 2 seconds. If you stop calling for two minutes, you're back to 60 tokens.

Handling 429

Every 429 response includes a Retry-After header in seconds.

HTTP/2 429
retry-after: 12
content-type: application/json

{ "error": "Rate limit exceeded" }

Sleep for at least that many seconds before retrying. Most HTTP clients honor Retry-After automatically.

Upgrading

Need higher limits? Reach out and we'll tune the buckets for your account.