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. |
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.