> ## 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

Which shape comes back depends on whether you sent either parameter:

<Tabs>
  <Tab title="Paginated envelope">
    Send `page`, `page_size`, or both:

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

  <Tab title="Plain array">
    Omit both, on an endpoint that supports it:

    ```json theme={null}
    [{ "id": "..." }, { "id": "..." }]
    ```
  </Tab>
</Tabs>

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.

## Pagination in the request body

The log list endpoints take `page` and `page_size` in the JSON body instead of the query string, because their filters do not fit in a URL. The parameters mean the same thing and take the same values.

For example, fetching the first page of 100 logs:

```bash theme={null}
curl -X POST "https://api.stackone.com/logs" \
  -u "$STACKONE_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "page_size": 100}'
```

The response is the same paginated envelope as everywhere else, so a paging loop reads identically whichever way the parameters went out.

## 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.

<Warning>
  Offset pagination reads a moving target. Records written while a sweep is in progress shift rows
  between pages, so a long run can miss a record or return one twice. Where the endpoint takes time
  bounds, set both ends so the set stops changing underneath you, and deduplicate on the record's
  id downstream.
</Warning>