Rate limits and usage tiers
Two separate limits apply to every key: a per-minute rate limit set by the account's usage tier, and the monthly quotas of its plan (plans).
Usage tiers
Rate limits rise automatically with payment history, whatever the plan. A tier changes only when a payment is confirmed by our payment provider; a failed payment never lowers it.
| Tier | Requests per minute, per key | Reached when |
|---|---|---|
| 0 | 10 | No payment yet |
| 1 | 60 | First successful payment |
| 2 | 300 | At least £100 paid in all, and the account at least 14 days old |
| 3 | 1,000 | At least £500 paid in all, and the account at least 30 days old |
| 4 | 3,000 | At least £2000 paid in all, and the account at least 60 days old |
Quotas
- Lookups per month come from the plan. Once used, prepaid credits pay for further lookups (oldest expiry first), then calls answer 429
quota_exceededuntil the month resets (UTC). - Watched entities are a hard limit of the plan, never billed as overage: an add over the limit answers 403
watch_limit_reachedand adds nothing. - With an API key, each successful answer, and each definitive "not found", costs the units stated for the operation (1 lookup for every lookup), including answers served from cache; other errors are refunded. Without a key: 25 lookups per client IP per UTC day; answers served from cache cost nothing. Once an IP's allowance is used, each distinct client on it gets 5 more a day (at most 20 per IP). Sample companies 03959649, 00519500, 2138001S47XKWIB7TH90, 552032534 are always free.
- Without a key: 25 lookups per client IP per UTC day, and 500 across all keyless callers.
- Free plans together make at most 5,000 upstream calls a day, so free traffic can never use up an official source's capacity; over it, free calls answer 429
rate_limited(next_action: upgrade).
Headers on every response
| Header | Meaning |
|---|---|
RateLimit-Limit |
requests allowed per minute for this key |
RateLimit-Remaining |
requests left in this minute |
RateLimit-Reset |
seconds until the minute resets |
Retry-After |
on a 429 or 503: seconds to wait |
Sisoco-Quota-Lookups-Remaining |
lookups left this month (keyless: today) |
Sisoco-Quota-Watch-Remaining |
entities you can still watch |
Sisoco-Request-Id |
this request, also in the body; quote it to support |
Sisoco-Version |
the API version that answered |