List endpoints page their results with two parameters: returnCount (page size) and skip (offset). Where you put them depends on the endpoint:
- GET list endpoints (for example
GET /v2/companies/by-website, GET /v2/explore/{listId}) take both as query parameters.
- POST filter endpoints (for example
POST /v2/companies) take both as fields in the JSON request body, alongside your filter criteria.
When in doubt, check the API reference — each operation page lists exactly where its parameters go.
Parameters
Walking a list
GET endpoints — query parameters
POST endpoints — body fields
Stop when a page returns fewer than returnCount records.
Picking a page size
- Small portfolios (< 1000 companies). Set
returnCount to the total — one request, no pagination.
- Large filtered lists. Set
returnCount=1000 and walk with skip. This is the most efficient mode.
- Insights enabled. When
?insights=true, aggregations cover the full matched set, not just the current page. Keep returnCount low (40–100) on the first call to get the aggregations cheaply; raise it on subsequent paging requests if you also want the rows.
Limits
returnCount > 1000 is rejected with 400. There’s no hard ceiling on skip, but very deep pagination (skip > 100,000) is slow — use filters or company-number sets to narrow the set instead.
Per-endpoint variations
A few endpoints document their own page-size parameters with different defaults (for example /v2/companies/by-website has its own returnCount). The API reference is authoritative — check each operation’s parameters before assuming the default.
Last modified on October 2, 2026
