Limits and errors

Limits

Limit	Value
Request rate	about 10 requests per second per IP address, with short bursts up to 20
Leads per browse page	1,000
Leads per export	50,000 (ask for more and capped_to_max tells you it was capped)
ICP description (target_icp)	500 characters

Over the request rate you get HTTP 503 from the edge — wait a second and retry with backoff.

Coverage you should know about

• US-focused data. 68.6 million people have a country, almost all in the US; every other country has under 30,000.
• Revenue bands are derived from headcount, not reported revenue — each revenue band matches a company-size band exactly.
• Counts with job titles, keywords or departments are estimates worked out from a sample of matching companies. The same request returns the same estimate, but the number of people an export actually delivers can differ from it.

Errors

Errors come back as JSON with an error message, and often a machine-readable code:

{ "error": "Unknown export", "code": "EXPORT_NOT_FOUND" }

Status	When	What to do
400	A required field is missing or malformed — for example leadIds array is required, or target_icp is required.	Fix the request body. The message says which field.
401	Authentication required (no key) or Invalid API key.	Send X-API-Key: ls_live_….
402	INSUFFICIENT_CREDITS — not enough credits for a reveal, scrape or enrichment job.	Top up or upgrade in Settings → Plans & Billing.
404	Unknown id — e.g. EXPORT_NOT_FOUND. A malformed id returns 400 BAD_ID.	Check the id came from job_id.
410	ENDPOINT_RETIRED — the old waterfall endpoints.	Use /leads/browse + /leads/reveal.
502	LEADS_SOURCE_DOWN / FACET_SOURCE_DOWN — the lead database didn’t answer in time.	Retry after a few seconds.
503	Rate limit.	Back off and retry.

When an export runs out of credits

An export doesn’t refuse upfront. It delivers rows until your credits run out, then stops and keeps what it delivered: the job finishes with status: "completed", capped: true, and deliveredRows lower than you asked for. You’re charged only for the rows in the file. If no row could be paid for at all, the job ends failed.

A search that returns 0

The API doesn’t reject unknown filter values; it matches nothing. If a count is unexpectedly zero:

1. Look at filters in the /leads/search response — it shows how your request was read.
2. Check each value against GET /api/v1/leads/filters?field=<name>.
3. Remove filters one at a time to find the one that empties the result.