> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedatacity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Page through list responses with returnCount and skip. Default page size is 40; maximum is 1000.

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](/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

```bash theme={null}
# 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

```bash theme={null}
# 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](/api-reference/guides/filtering) or [company-number sets](/api-reference/guides/batching) 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](/api-reference) is authoritative — check each operation's parameters before assuming the default.

<Snippet file="need-help.mdx" />