Plans and limits
Rate limits
Two limits apply to every request: a per-minute limit for each key and a monthly quota for your account.
| Plan | Requests / minute (per key) | Requests / month (per account) | Active keys |
|---|---|---|---|
| Free | 60 | 1,000 | 3 |
| Pro | 600 | 100,000 | 10 |
Minutes and months are UTC: the minute window resets on the minute, the quota on the 1st of each month at 00:00 UTC. The monthly quota is shared by all keys on your account. Requests refused with 429 don't count towards either limit; every other answer to a valid key (including 400 and 404) counts as one request. More than 30 requests a minute with invalid keys from one address are refused with 429 for a minute. Need more? Upgrade to Pro.
Headers
Every authenticated response tells you where you stand:
| X-RateLimit-Limit | Requests allowed per minute for this key. |
|---|---|
| X-RateLimit-Remaining | Requests left in the current minute. |
| X-RateLimit-Reset | When the minute window resets (Unix seconds). |
| X-RateLimit-Limit-Month | Requests allowed this month for your account. |
| X-RateLimit-Remaining-Month | Requests left this month. |
| X-RateLimit-Reset-Month | When the month resets (Unix seconds). |
| X-Kindred-Plan | free, pro or unlimited. |
| Retry-After | On 429 only: seconds to wait before retrying. |
When you hit a limit
You get 429 with rate_limited (the minute) or quota_exceeded (the month) and a Retry-After header. Wait that long, then retry.
{
"error": {
"code": "rate_limited",
"message": "This key is limited to 60 requests a minute on the Free plan. Retry in 23 s."
}
}Staying under the limits
- Cache on your side. Events change slowly: refreshing every 15 to 60 minutes is plenty for most sites.
- Send
If-None-Matchwith the lastETag; an unchanged response is a tiny304. - Ask for
limit=100and filter server-side (country,category, dates) instead of fetching everything. - Don't call the API on every page view from the browser: fetch on your server and serve your own copy.
Staff accounts