Using the API

Rate limits

Too many requests answer 429 with a Retry-After header. Wait that long and try again.

Requests are limited per key and per account, so one runaway integration cannot spend the whole account's allowance, and per network address as a backstop. A request over a limit is refused before it reaches anything that costs money.

The limits

Limit	Requests a minute	Counts
Per key, `read` operations	120	Every call of an operation whose scope is `read`, such as `list_leads` or `estimate_scrape`
Per key, `write` operations	30	Every call of an operation whose scope is `write`, such as `stop_scrape`
Per key, `spend` operations	12	Every call of an operation that takes credits
Per account	300	Every call of every key on the account, API and MCP keys alike
Per network address	600	Every request to the HTTP API, and separately to the MCP server
Checkouts per account	6	`create_checkout` and `create_top_up_checkout` together, beside their `write` limit, because each one opens a checkout at the payment provider

A call spends its key's limit first and then the account's, so a key that has run out stops before it can draw down what the account's other keys share. A download link spends only the address limit: the token in it is its credential.

When you are limited

The API answers 429 with the code rate_limited, a Retry-After header giving the seconds to wait, and the same number as retryAfterSeconds in the body:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{ "error": "rate_limited", "message": "Too many requests. Wait for the Retry-After seconds and try again.", "retryAfterSeconds": 12 }

Wait that long, then send the same request again. A spending call retried after a 429 should carry its original Idempotency-Key.

Staying under the limits

Poll slowly. A running scrape needs get_scrape_status every 30 to 60 seconds, not more. See Polling and status.
Page large. Ask for the largest limit an operation allows rather than many small pages.
Download once. For a finished scrape's whole list, one call to download_leads replaces hundreds of pages.
Cache the catalog. Niches, prices and territories carry a version and change rarely. Keep a copy and refresh it when the version moves.

The limits may change as the API grows. Code that honours Retry-After keeps working whatever they are.

A 503 try_again with Retry-After is not a rate limit. It means Leadity could not answer just then, or that a spend's Idempotency-Key is still being processed by an earlier request: retry after that many seconds, with the same key on a spend. See Errors and Idempotency.