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

# Pagination

> Handling pagination on List endpoints.

Most list endpoints can be paginated with the following parameters. Check the endpoint's reference page for where it takes them and what limits it sets.

<ParamField query="page" type="integer">
  The 1-based page number to fetch.
</ParamField>

<ParamField query="page_size" type="integer" default="25">
  Records per page, up to the maximum the endpoint allows.
</ParamField>

For example, fetching the first page of 50 accounts:

```bash theme={null}
curl "https://api.stackone.com/v2/accounts?page=1&page_size=50" \
  -u "$STACKONE_API_KEY:"
```

## Two response shapes

Send either parameter and the response is a paginated envelope:

```json theme={null}
{
  "page": 1,
  "page_size": 25,
  "total": 342,
  "data": [{ "id": "..." }]
}
```

Some endpoints also return every record as a plain array when both parameters are omitted:

```json theme={null}
[{ "id": "..." }, { "id": "..." }]
```

An endpoint that can return both declares them on its response, so a generated client covers either. Pick one before you write the code that reads it, since the two are not interchangeable.

## Paging through a full set

Read `total` from the first response to know how many pages to expect, then request each in turn.

Keep `page_size` the same across a sequence. Changing it partway through repeats or skips records, because the offset is derived from both values.