Browse documentation
Rate limits
Monthly quotas, response headers, request costs, control-graph limits and tier access. For why there are two separate limits, see Capacity and quotas.
Monthly quota
| Tier | Price | Monthly requests |
|---|---|---|
| Free | £0 forever | 500 |
| Growth | £29 /month | 10,000 |
| Enterprise | £149 /month | 50,000 |
Quota window
- Counted per
- Account. Usage is metered per account, not per key.
- Growth and Enterprise
- The quota window is your Stripe billing period.
- Free
- The quota window rolls monthly from the key's creation time (UTC).
- Short months
- A window that would end on a day the month lacks (29th to 31st) ends on the month's last day. The next window starts from there.
- Reset time
X-RateLimit-Reset. Windows are per key, not calendar months.- Regenerated paid key
- Keeps the billing period and the usage already counted.
Response headers
| Header | Format | Example | Present on | Meaning |
|---|---|---|---|---|
X-RateLimit-Limit | Integer | 10000 | Every authenticated response | Your monthly quota. |
X-RateLimit-Remaining | Integer | 9847 | Every authenticated response | Requests left in the current window, after this request and any refund. |
X-RateLimit-Reset | Unix timestamp (seconds) | 1767225600 | Every authenticated response | When the current quota window ends. |
Retry-After | Integer seconds | 12 | Every 429 and 503 | How long to wait before sending the request again. |
X-Response-Time | Milliseconds, e.g. 84ms | 84ms | Most endpoint responses. Absent on 401, rate_limit_exceeded and some 403 and 422 responses | Server processing time. Informational only. |
Request cost
A request costs one unit of quota however many sources or graph nodes it touches. Cache hits cost the same as cold lookups.
| Outcome | Monthly quota |
|---|---|
200, complete response | 1 request |
200, partial response (sources_failed not empty, or a graph with status: partial) | 1 request |
401 authentication errors | Not consumed |
403 tier errors, 404, 422 validation errors | 1 request |
429 rate_limit_exceeded | Nothing left to consume |
429 upstream_capacity | Refunded |
429 control_graph_capacity | 1 request, not refunded |
500 internal_error, 502 upstream_error | 1 request |
503 upstream_unavailable | Refunded |
MCP tools/call, including tool errors | 1 request, never refunded |
MCP tools/call of get_account_status | Not counted |
MCP protocol messages (initialize, tools/list and similar) | Not consumed, but refused once the quota is spent |
Control-graph limits
These are ceilings, not reserved throughput. Shared capacity can stop a graph sooner; see Capacity and quotas.
| Limit | Growth | Enterprise |
|---|---|---|
| Admission burst | 6 graphs | 12 graphs |
| Admission refill | 6 per minute | 12 per minute |
| Concurrent graphs per account | 1 | 1 |
| Concurrent graphs across the platform | 2, shared | 2, shared |
Ancestor depth (max_depth) | 1–4, default 4 | 1–6, default 6 |
Company nodes, including the subject (max_nodes) | 1–12, default 12 | 1–24, default 24 |
| Outbound Companies House attempts per graph | 20 | 30 |
| Deadline per graph | 8 seconds | 12 seconds |
| Descendant depth from each anchor | 2 | 2 |
| Retained edges | 100 | 100 |
- Pagination and failed attempts count towards outbound attempts. Cache hits do not.
- A graph that cannot start returns
429control_graph_capacity. A graph stopped by a limit returns200withstatus: partial,coverageandfrontier. - The graph endpoint has no
freshparameter.
Tier access
| Endpoint or feature | Free | Growth | Enterprise |
|---|---|---|---|
GET /entity/{company_number} | Yes | Yes | Yes |
Embedded risk_signals on the entity response | Omitted from the response, no error | Yes | Yes |
ch, ch_psc, insolvency, charges, officers sources | Yes | Yes | Yes |
land source | Omitted, or invalid_sources if it is the only source | Yes | Yes |
GET /entity/{company_number}/risk | 403 risk_tier_required | Yes | Yes |
GET /entity/{company_number}/control-graph | 403 control_graph_tier_required | Yes | Yes |
GET /officers/{officer_id}/appointments | 403 appointments_tier_required | Yes | Yes |
GET /search | Yes | Yes | Yes |
MCP tools have the same tier gates as their REST equivalents. A blocked tool returns the same code in the tool result.
The three 429 codes
| Code | Cause | Retry-After means |
|---|---|---|
| rate_limit_exceeded | Your monthly quota is spent. | Seconds until your quota window ends. Can be days. |
| upstream_capacity | The shared Companies House budget is exhausted. | Seconds until the budget has refilled enough. Usually short. |
| control_graph_capacity | A graph could not be admitted or its subject lookup was shed. | Seconds until a graph slot or admission allowance is likely free. |
Usage and upgrades
- Current usage: dashboard → Usage.
- Change tier: dashboard → Billing or the pricing page.
- Tier changes apply to your existing key. The key never changes.