Pagination - The Data City

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

Parameter	Type	Default	Range	Purpose
`returnCount`	integer	`40`	1–1000	Maximum number of records to return.
`skip`	integer	`0`	≥ 0	Number 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.

​Parameters

​Walking a list

​GET endpoints — query parameters

​POST endpoints — body fields

​Picking a page size

​Limits

​Per-endpoint variations