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

ParameterTypeDefaultRangePurpose
returnCountinteger401–1000Maximum number of records to return.
skipinteger0≥ 0Number of records to skip before returning.

​
Walking a list

​
GET endpoints — query parameters

# Page 1 — first 100 records
curl 'https://product-api.thedatacity.com/api/v2/companies/by-website?url=acme.com&returnCount=100' \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Page 2 — next 100
curl 'https://product-api.thedatacity.com/api/v2/companies/by-website?url=acme.com&returnCount=100&skip=100' \
  -H 'Authorization: Bearer YOUR_API_KEY'

​
POST endpoints — body fields

# Page 1
curl -X POST 'https://product-api.thedatacity.com/api/v2/companies' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"rtics": ["RTIC-12345"], "returnCount": 100}'

# Page 2
curl -X POST 'https://product-api.thedatacity.com/api/v2/companies' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"rtics": ["RTIC-12345"], "returnCount": 100, "skip": 100}'
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 May 19, 2026