API rate limits

Each key can make a set number of requests a minute, depending on the account's plan. The limit belongs to the key, not the account, so two tools with their own keys do not use each other's allowance.

Reading the limit from a response#

Every response to a request the key's limit admitted, an error included, reports the key's limit and what is left of it, in the IETF RateLimit header fields:

RateLimit-Policy: "minute";q=60;w=60
RateLimit: "minute";r=42;t=17

• In RateLimit-Policy, q is the key's limit and w the window in seconds.
• In RateLimit, r is the requests left in this window and t the seconds until it resets.

A refusal that comes before the key's limit is counted carries no RateLimit fields, such as a key or plan refusal (a 401 or 403), api_key_in_url, a 429 for too many failed attempts or a 503. A 429 from the key's own limit carries them.

GET /v1/account returns the same limit as rate_limit.requests_per_minute.

At the limit#

A request over the limit is refused with 429 and the code rate_limited. The Retry-After header, and retry_after_seconds in the body, say how many seconds to wait. Wait that long, then retry; retrying sooner is refused again.

If the service that counts requests is briefly unavailable, the API refuses the request with 503 and service_unavailable rather than serve it uncounted. Its Retry-After is 5 seconds.

Using fewer requests#

• A brand is tracked every 7 days, so the numbers change at most once a run. Reading the reports once a day is plenty for a dashboard.
• Reports are kept for 10 minutes for the same window and filters, so asking again within that time returns the same figures, unless a run completes in between.
• Read lists with the largest limit your tool can handle (see Pagination).
• Retry a 429 or 503 after the Retry-After delay, and back off further if it repeats.