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:

NamespaceDefaultCounted for
discovery_traversal80 sweeps a day (the daily trace-sweep limit)the calling organisation
discovery_source_dispatch60 one-tier searches an hourthe calling organisation
discovery_source_daily20 inferred-scope discovery sweeps a day (UTC; neither commodity nor product, or no country given)the calling organisation
discovery_source_direct_operated120 direct-operated searches an hourthe calling organisation
discovery_validate300 supplier resolutions an hourthe calling organisation
screening_validate300 public-funnel resolutions an hourthe calling organisation
screen_run25 Risk Screening runs a daythe calling organisation
ingestion_asset_create60 uploads an hourthe organisation the key acts for
attachment_create60 attachment uploads an hourthe 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

FieldDescription
namespaceThe service area (e.g. "cadastral").
enabledtrue when at least one service in this namespace is active for your organisation. If false, requests to this namespace will be rejected.
configuredtrue when access has been set up for your organisation โ€” even if currently disabled. If false, your organisation has not been granted access; contact support.
servicesAn array of service entries (see below). May be empty if configured is false.

Fields per service entry

FieldDescription
service_labelThe display name of the service (e.g. "US Cadastral").
enabledtrue when this specific service is active for your organisation.
limits.max_requestsThe maximum number of requests allowed per window.
limits.window_secondsHow long the window is, in seconds.
limits.current_usageHow 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.remainingHow much budget is left before requests start being rejected (max_requests - current_usage).
limits.resets_atThe 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

FieldDescription
enabledfalse 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.
configuredtrue when your organisation has its own limit in place of the default.
servicesAlways [].
limit.windowminute, hour or day, or custom for another length.
limit.window_secondsThe window length, in seconds.
limit.allowedThe limit for one window: your organisation's own when configured, otherwise the default.
limit.usedCounted in the current window. A traversal counts its whole max_sweeps while it runs, and gets back the unused sweeps when it settles.
limit.remainingLeft in the current window, never below 0.
limit.resets_atWhen 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 remaining reaches zero, further requests to that service are rejected until the window resets at resets_at. Rejected items appear in the response with a status of Failed and 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 remaining on the relevant service, and split the batch across windows if you don't have enough headroom.
  • When a batch comes back with some Failed items โ€” check this endpoint to see whether you hit the limit, and use resets_at to schedule the retry.
  • When you're not sure why a request is rejected โ€” check configured and enabled first. configured: false means support needs to grant access; enabled: false means access has been paused.

The response covers the organisation the key belongs to.

Required scope: rate_limits:read or discovery:write.