Rate limits & credits
Two independent meters govern API usage: rate limits cap how often you can call (per minute and per day, by plan), and credits meter how much data you take out.
Plan limits
| Plan | Requests / minute | Requests / day |
|---|---|---|
| Free | 20 | 1,000 |
| Starter | 30 | 5,000 |
| Pro | 100 | 50,000 |
Limits apply per organization across all keys and all search-family endpoints (/search, /lookup, /similar). Need more? Upgrade your plan or talk to us.
Rate-limit headers
Successful responses include your daily budget state:
| Header | Meaning |
|---|---|
| X-RateLimit-Limit | Your plan's daily request limit. |
| X-RateLimit-Remaining | Requests left today. |
Handling 429 responses
Exceeding either window returns 429 with a Retry-After header (seconds until the window resets):
{
"error": "rate_limit",
"limit": 20,
"period": "minute",
"retry_after": 42
}
Respect Retry-After rather than retrying immediately — hammering a 429 just extends the backoff. For burst workloads, spread calls across the minute or queue them client-side.
Credits
Credits are charged only when the API returns data:
- Search & similar — 1 credit per strong (verified) result returned. Partial matches are free.
- Lookup — 1 credit per call when at least one name resolves; no-match calls are free.
- Company details — 1 credit when the company exists; 404s are free.
Every metered response carries credits_used and credits_remaining. When your balance can't cover a request you get 402 — see Errors. Buy more or upgrade on the billing page.