Skip to main content
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 7, 2026