Rate Limits and Quotas

Two independent limits protect the platform. The request rate limit caps how fast you can call the API; the monthly record quota caps how much distinct data you can extract over a calendar month. They are measured separately and return separate 429 codes - branch on code, not on the HTTP status alone.

Both limits are keyed to your account (seat), not to an individual key. Issuing extra keys does not raise either budget - all of an account's keys draw from the same rate-limit window and the same monthly quota.

Request rate limit

200 requests per minute, per account, across all of that account's keys.
Applies to every bearer-token API - both the Public Company API (/api/v1, /api/v2) and Private Data API (/api/private/v1).
The window is a fixed 60-second bucket. When you exceed it, further requests return 429 RATE_LIMITED until the window rolls over.

A throttled response includes headers telling you how long to wait:

Header	Meaning
`Retry-After`	Seconds until the current window resets.
`X-RateLimit-Limit`	The per-minute ceiling (`200`).
`X-RateLimit-Remaining`	Requests left in the window (`0` on a `429`).

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit of 200 requests/minute exceeded. Retry in 12s."
  }
}

Handling it: on a 429 RATE_LIMITED, sleep for Retry-After seconds and retry. A simple client-side cap of a few requests per second leaves comfortable headroom.

Monthly record quota

The Private Data API additionally meters the distinct records you pull each calendar month. (The Public Company API is not metered this way - it is governed only by the request rate limit above.)

20,000 distinct records per account, per calendar month.
A record is one company, one deal, or one investor. Each type is counted in its own bucket, so the same underlying organisation appearing as both a company and an investor counts once in each.
Re-pulling a record you have already fetched this month is free. The quota counts distinct records: only records you have not seen yet this month draw down the budget. You can re-request the same companies, deals, or investors as often as you like - poll for updates, page back through a list, re-sync your mirror - without spending quota a second time.
The counter resets at 00:00 UTC on the 1st of each month.

Because only new records are charged, a typical incremental-sync workload (pull once, then fetch only what changed via the change feed) consumes far less than its raw row count suggests.

Quota headers

Every successful (200) Private Data API response carries your current standing, so you can track consumption without a separate call:

Header	Meaning
`X-Records-Limit`	The monthly ceiling (`20000`).
`X-Records-Used`	Distinct records charged so far this month, including this request.
`X-Records-Remaining`	Records left before the cap.
`X-Records-Reset`	Unix timestamp (seconds) of the next reset - 00:00 UTC on the 1st.

When the quota is exhausted

If a request would pull new records beyond the remaining budget, the whole request is rejected with 429 MONTHLY_RECORD_LIMIT - no partial data is returned, and nothing is charged. The same X-Records-* headers are included so you can see exactly how much room is left.

{
  "error": {
    "code": "MONTHLY_RECORD_LIMIT",
    "message": "Monthly limit of 20000 distinct records reached: this request needs 250 new record(s) but only 80 remain this month. Re-requesting records you've already pulled this month is free; request fewer new records, or wait for the reset on the 1st."
  }
}

Handling it: request fewer new records (a smaller limit, or a narrower filter), fall back to records you have already pulled this month (those never count), or wait for the monthly reset.

Generate Authorization Token

Migration to API v2