Docs / Shared / Rate limits & quotas

Rate limits & quotas

Every response carries your current budget, so a client can back off before it is refused rather than after.

Headers

X-RateLimit-Limit: <your burst>    // bucket capacity, from the table below
X-RateLimit-Remaining: 97          // requests left in it right now
X-RateLimit-Reset: 1          // seconds until a slot frees up
// on a 429 only
Retry-After: 1

Limiting is a token bucket, not a fixed window. Your plan's bucket holds a burst of requests and refills continuously at the sustained rate, so X-RateLimit-Remaining counts down out of X-RateLimit-Limit and climbs back on its own — there is no window boundary to line up with, which is why Reset is a countdown to the next free slot rather than a timestamp.

The monthly allowance

X-Quota-Limit: <your monthly>      // from the table below, or your own agreed allowance
X-Quota-Used: 412                  // including this request
X-Quota-Remaining: 588             // 0 on the refusal

The two limits are separate and answer different questions: the rate limit is how fast, the allowance is how much. Crossing the allowance is a 429 with quota_exceeded rather than rate_limited, and it carries no Retry-After — waiting does not help, because the allowance resets on the 1st.

One request is one credit, and only a successful one counts. A 4xx or a 5xx spends nothing: a mistyped filter costs a 400 and no allowance, and a request that failed on our side is not one you paid for. limit is capped at 100, so a credit is at most a hundred rows and the ceiling is knowable in advance.

Requests are counted per account, not per key — a customer with three keys has one allowance and one bucket between them. If you are polling for changes, first_seen_after is the parameter that decides your bill: a complete daily feed of everything new is a few hundred requests a month, while re-downloading the collection to find them is that many every day.

By plan