Rate limits and quotas

Two kinds of limit apply to a key: a request rate, enforced per minute on every call you make, and quotas on what your jobs consume, counted per UTC day and month. Both are readable from GET /usage.

Requests per minute

Each key has a requestsPerMinute allowance; a new self-serve key gets 120. It is counted in one-minute windows: the first call opens a window, the whole minute's allowance can be spent in a burst, and past it calls are refused until the window ends. All the keys on one account share one count, so a second key (or a rotated one) adds no allowance. Every authenticated call counts: submissions, polls of GET /jobs/{id}, record pages and GET /usage alike.

Every response carries the allowance and what is left of it. Over the limit, the API answers 429 and retry-after says how many seconds to wait:

Headers

HTTP/1.1 200 OK
x-ratelimit-limit: 120
x-ratelimit-remaining: 119

HTTP/1.1 429 Too Many Requests
x-ratelimit-limit: 120
x-ratelimit-remaining: 0
retry-after: 4

{ "ok": false, "error": "rate limit exceeded (120/min); retry in 4s" }

Keep polling loops to one request every few seconds, and read records with limit=1000 or more rather than many small pages.

Failed attempts

Separately from the per-key limit, 20 requests with a bad or missing key from one address within 60 seconds lock that address out with 429 too many failed auth attempts; retry later until the window passes. A valid key on an account that cannot be billed answers 402 and does not count.

Job limits

Quota	New key	What it bounds
`concurrentJobs`	2	Jobs of this key running at once. Further jobs wait in the queue; nothing is refused.
`queuedJobs`	10	Jobs of this key waiting to start. One more answers `429` `too many queued jobs for this key (10); wait for running jobs to finish`.

When the service as a whole has no room left in its queue, a submission answers 429 server saturated; retry shortly; wait a few seconds and submit again.

Daily and monthly quotas

Paid work has no daily or monthly ceiling. Records you are billed for never count toward these quotas, however many you collect, and neither do requests that fail on our side. They count only what your inputs use without producing a billed record: invalid inputs, searches that find nothing, misses a source cannot tell apart from a failure. A lookup the source answers "not found" is a billed record, so it never counts here. They are updated when a job settles, so a running job's usage appears at its end. An account that reaches one answers 429 to new submissions with the message in the last column until the window turns over at midnight UTC.

Quota	New key	What it counts	Message at the limit
`unbilledRequestsPerDay`	20,000	Requests your inputs used without producing a billed record, such as an invalid input or a search that found nothing. Per UTC day, across all your keys.	`unbilled request limit reached for this account`
`unbilledMbPerDay`	2,000 MB	Data transferred for those same requests. Per UTC day, across all your keys.	`unbilled bandwidth limit reached for this account`

A running job is also stopped part-way when most of what it produces is unbilled and it has used more than the account has left for the day. The records it delivered before then are kept, and its error says which limit it reached. A job whose billed records outnumber its unbilled ones is never stopped this way.

Quotas that are not listed for a new key (recordsPerDay, recordsPerMonth, maxItemsPerJob, usdPerDay, usdPerMonth, unbilledRequestsPerMonth, unbilledMbPerMonth) are uncapped and show as null in GET /usage.

The credit balance is not one of these: it does not reset at UTC midnight, and reaching it answers 402, not 429. Every delivered record is paid from the account's prepaid credit, across all its keys; delivery stops at the last record the balance covers, and nothing is owed. Pricing and billing covers buying more; Authentication lists the exact 402 wording.

Read them from GET /usage

GET /usage returns the current UTC day and month for the key that made the call, with every quota next to the counter it bounds.

Example usage

{  "ok": true,  "usage": {    "key": "production",    "day": {      "key": "2026-09-23",      "records": 1284,      "cost": 6.163,      "limit": null,      "remaining": null    },    "month": {      "key": "2026-09",      "records": 5910,      "cost": 28.368,      "limit": null,      "remaining": null    },    "events": {      "amazon/product": 5910    },    "resources": {      "day": {        "requests": 4120,        "bandwidthMb": 612.5,        "unbilledRequests": 18,        "unbilledRequestsLimit": 20000,        "unbilledMb": 2.4,        "unbilledMbLimit": 2000      },      "month": {        "requests": 19860,        "bandwidthMb": 2894.2,        "unbilledRequests": 91,        "unbilledRequestsLimit": null,        "unbilledMb": 11.8,        "unbilledMbLimit": null      }    },    "quotas": {      "recordsPerDay": null,      "recordsPerMonth": null,      "concurrentJobs": 2,      "maxItemsPerJob": null,      "usdPerDay": null,      "usdPerMonth": null,      "unbilledRequestsPerDay": 20000,      "unbilledRequestsPerMonth": null,      "unbilledMbPerDay": 2000,      "unbilledMbPerMonth": null,      "queuedJobs": 10,      "requestsPerMinute": 120    },    "prices": {      "amazon/product": 4.8    }  }}

Example data for a new key. A null limit means the quota is uncapped.

day and month: records billed and spend in USD for the window, with the record quota and what is left of it.
events: records billed this month per site/event, the same names as the price list.
resources: per window, the requests and megabytes this key's jobs used, billed or not (requests, bandwidthMb, for information only), and the unbilled requests and megabytes that count against the quotas above, next to their limits.
quotas: every quota on the key, null when uncapped.
prices: USD per 1,000 records per site/event for this key.

Next step

Pricing and billing explains the prices behind day.cost and how credits pay for them.