Get Rate Limits
Show the rate limits enforced on your organisation and how much of each is left. Use it before a large parcel batch, a traversal or a run of uploads, so a limit does not refuse the work part-way.
The first entry is cadastral, broken down by service. Then comes one entry per per-organisation limit, each with a limit object:
| Namespace | Default | Counted for |
|---|---|---|
discovery_traversal | 80 sweeps a day (the daily trace-sweep limit) | the calling organisation |
discovery_source_dispatch | 60 one-tier searches an hour | the calling organisation |
discovery_source_daily | 20 inferred-scope discovery sweeps a day (UTC; neither commodity nor product, or no country given) | the calling organisation |
discovery_source_direct_operated | 120 direct-operated searches an hour | the calling organisation |
discovery_validate | 300 supplier resolutions an hour | the calling organisation |
screening_validate | 300 public-funnel resolutions an hour | the calling organisation |
screen_run | 25 Risk Screening runs a day | the calling organisation |
ingestion_asset_create | 60 uploads an hour | the organisation the key acts for |
attachment_create | 60 attachment uploads an hour | the organisation the key acts for |
Not reported here:
- Lifetime allowances (discovery Traces, Risk Screening runs) โ read them on
GET /rate-limits/allowances. - The request limit โ every response carries it in the
x-ratelimit-*headers. It counts requests per source address.
โถWhat the response tells you
The response is grouped by namespace (a service area, such as cadastral) and contains one entry per service within that area. Each service entry shows your current quota usage, how much is left, and when the window resets.
โถTop-level fields per namespace
| Field | Description |
|---|---|
namespace | The service area (e.g. "cadastral"). |
enabled | true when at least one service in this namespace is active for your organisation. If false, requests to this namespace will be rejected. |
configured | true when access has been set up for your organisation โ even if currently disabled. If false, your organisation has not been granted access; contact support. |
services | An array of service entries (see below). May be empty if configured is false. |
โถFields per service entry
| Field | Description |
|---|---|
service_label | The display name of the service (e.g. "US Cadastral"). |
enabled | true when this specific service is active for your organisation. |
limits.max_requests | The maximum number of requests allowed per window. |
limits.window_seconds | How long the window is, in seconds. |
limits.current_usage | How much of this window's budget has been used so far. For most services this is the number of upstream requests counted toward the limit; for services configured to count cache hits, it also includes hits served from cache, matching what the quota check actually enforces. |
limits.remaining | How much budget is left before requests start being rejected (max_requests - current_usage). |
limits.resets_at | The ISO 8601 timestamp when the current window ends and current_usage resets to zero. May be null if no requests have been counted yet. |
limits is omitted from a service entry when no quota has been configured for that service โ contact support if you see this on a service you're trying to use.
โถFields per organisation limit
| Field | Description |
|---|---|
enabled | false when the limit does not apply: discovery_traversal without a traversal grant, or screen_run for an organisation with no Screen limit. Every other limit is true. |
configured | true when your organisation has its own limit in place of the default. |
services | Always []. |
limit.window | minute, hour or day, or custom for another length. |
limit.window_seconds | The window length, in seconds. |
limit.allowed | The limit for one window: your organisation's own when configured, otherwise the default. |
limit.used | Counted in the current window. A traversal counts its whole max_sweeps while it runs, and gets back the unused sweeps when it settles. |
limit.remaining | Left in the current window, never below 0. |
limit.resets_at | When the current window ends (ISO 8601, UTC). Windows are aligned to UTC, so a daily limit resets at 00:00 UTC. |
The daily trace-sweep limit applies to every organisation, including one with unlimited Traces. The daily screen_run limit applies only while the organisation has a Screen limit.
A request over a limit returns 429 RATE_LIMIT_EXCEEDED, and data.details carries the same counts plus limit and requested. See the error code reference.
โถHow rate limits work
- Each service has its own independent window. Hitting the cap on one service does not affect others.
- A request counts toward the limit of the service that handles it. For requests that may be served by more than one backend (for example, a cadastral lookup across multiple regions), each backend's quota is debited only for the items it handles.
- When
remainingreaches zero, further requests to that service are rejected until the window resets atresets_at. Rejected items appear in the response with a status ofFailedand a message describing the limit and when to retry. - For batch endpoints (e.g. parcel search), items that fit within the remaining quota are processed; items that would exceed it are rejected individually. You can read each item's status from the task result.
โถPractical use
- Before a large batch โ fetch this endpoint, sum your batch size against
remainingon the relevant service, and split the batch across windows if you don't have enough headroom. - When a batch comes back with some
Faileditems โ check this endpoint to see whether you hit the limit, and useresets_atto schedule the retry. - When you're not sure why a request is rejected โ check
configuredandenabledfirst.configured: falsemeans support needs to grant access;enabled: falsemeans access has been paused.
The response covers the organisation the key belongs to.
Required scope:
rate_limits:readordiscovery:write.