API

Rate limits & page sizes

How much you can pull per request, per minute, and per export — every number measured.

Every number here is measured against real data, not chosen to look good. Two scripts in the repo re-measure them and fail the build if a published limit stops being deliverable.

Reading leads

2,500 leads	Max per page on GET /api/v1/leads (default 50). Page with limit + offset; the response returns next_offset until you reach the end.
1,000 leads	Max per MCP tool call (default 25). Lower on purpose — MCP results are fed into a model's context window, so a huge page costs you tokens you can't use. Use export for volume.
120/minute	Requests per API key. Exceeding it returns 429; retry after the window.
8/minute	New searches per account — searches call paid data providers, so they're metered separately from reads.

Running searches

250 cities	Max cities in one bulk search. A sanity ceiling on job size — your plan's daily city budget is the bound you are more likely to meet.
250 searches/day	Separate from the city budget and counted per search, not per city: API calls, enrichment requests and automation runs all count. Exceeding it returns 429 and it resets within 24 hours.
100–550 cities/day	Daily city budget, by plan: Solo 100, Pro 300, Business 500, Unlimited 550 (Free 50). Exceeding it returns 429 and it resets within 24 hours. On a metered plan the city budget is far larger than the lead allotment can pay for, so the leads run out first; on Unlimited the 210,000-per-7-day-period limit is what binds.
50/day	Enrichment requests (POST /api/v1/enrich, MCP enrich_domains) per account per day. Exceeding it returns 429; it resets within 24 hours.
10 in flight	Max searches queued or running per account at once. A new search past that returns 429 naming the limit. Free a slot by waiting for one to complete, or cancel a queued search with DELETE /api/v1/searches/:id. Accounts are served fairly — every account with work gets one running search at a time, in the order created — so submit large batches in waves of 10.

There is no single response that can carry 50,000 leads — ours or anyone’s. A serverless response is capped at 4.5 MB and a fully verified lead is about 1 KB, so past a few thousand rows the honest answer is pagination for reading and an export job for bulk.

Bulk export (POST /api/v1/exports) — writes a file or pushes to your CRM, so it isn’t bound by the response cap:

50,000 leads	Per CSV or XLSX export. Returns a download link, and the file is emailed to you.
25,000 leads	Per JSON export. Lower than CSV because JSON repeats every field name on every row — the same leads are roughly three times the bytes.
5,000 leads	Per Google Sheets export — one append request, which Sheets caps by payload size.
1,000 leads	Per Close or GoHighLevel export. Much lower, because CRMs take one API call per lead — this is a time limit, not a size limit. For a bigger push, export CSV and import the file.

If more leads match than the limit, the export still runs and the response sets truncated: true with the limit that applied. It will never quietly hand you part of a list and call it done.