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

# Pagination

> Page through list endpoints with limit and offset query parameters.

List endpoints — `GET /v1/payment-intents`, `GET /v1/reconciliation-cases`, `GET /v1/api-keys`, `GET /v1/audit-events`, `GET /v1/outbound-webhook-events`, and similar — use **offset-based pagination** with two query parameters.

## Query parameters

<ParamField query="limit" type="integer">
  Number of items to return. Minimum `1`, maximum `100`. Default varies by endpoint — most list endpoints default to `25`; `GET /v1/audit-events` and `GET /v1/api-keys` default to `50`. Check the endpoint's reference page for its exact default.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of items to skip from the start of the result set. Minimum `0`.
</ParamField>

```bash theme={null}
curl "https://api.reconlayer.com/v1/payment-intents?limit=25&offset=50" \
  -H "Authorization: Bearer $RECONLAYER_API_KEY"
```

## Response shape

Every paginated list endpoint returns the same envelope:

```json theme={null}
{
  "items": [ /* page of results */ ],
  "total": 128,
  "limit": 25,
  "offset": 0
}
```

<ResponseField name="items" type="array" required>
  The page of results. Each item's shape depends on the endpoint (e.g. a `PaymentIntent` summary, a `ReconciliationCaseSummary`, an `ApiKeySnapshot`).
</ResponseField>

<ResponseField name="total" type="integer" required>
  Total number of items matching the request's filters, across all pages — not just the current page.
</ResponseField>

<ResponseField name="limit" type="integer" required>
  Echoes the `limit` used for this request (after defaulting).
</ResponseField>

<ResponseField name="offset" type="integer" required>
  Echoes the `offset` used for this request.
</ResponseField>

## Traversing all pages

Increment `offset` by `limit` until `offset >= total`:

<CodeGroup>
  ```bash curl theme={null}
  limit=25
  offset=0

  while true; do
    page=$(curl -s "https://api.reconlayer.com/v1/payment-intents?limit=$limit&offset=$offset" \
      -H "Authorization: Bearer $RECONLAYER_API_KEY")

    echo "$page" | jq '.items[]'

    total=$(echo "$page" | jq '.total')
    offset=$((offset + limit))
    if [ "$offset" -ge "$total" ]; then
      break
    fi
  done
  ```

  ```javascript Node.js theme={null}
  const limit = 25;
  let offset = 0;
  let total = Infinity;

  while (offset < total) {
    const res = await fetch(
      `https://api.reconlayer.com/v1/payment-intents?limit=${limit}&offset=${offset}`,
      { headers: { Authorization: `Bearer ${process.env.RECONLAYER_API_KEY}` } },
    );
    const page = await res.json();

    for (const item of page.items) {
      // process item
    }

    total = page.total;
    offset += limit;
  }
  ```
</CodeGroup>

## Filtering combined with pagination

Most list endpoints accept additional filter query parameters alongside `limit` and `offset` — for example `GET /v1/payment-intents` accepts `status` and `externalReference`, and `GET /v1/reconciliation-cases` accepts `status`, `reconciliationStatus`, and `externalReference`. `total` reflects the count **after** filters are applied, so traversal logic works the same way whether or not you're filtering.

```bash theme={null}
curl "https://api.reconlayer.com/v1/reconciliation-cases?reconciliationStatus=unreconciled&limit=25&offset=0" \
  -H "Authorization: Bearer $RECONLAYER_API_KEY"
```

<Note>
  Sending an out-of-range `limit` (e.g. above `100`) or a negative `offset` returns `400 invalid_request` with an `issues` array — see [Errors](/api-reference/errors#validation-errors-400-invalid_request).
</Note>

## Next steps

* [Errors](/api-reference/errors) — validation error shape for out-of-range pagination parameters.
* [Rate limits](/api-reference/rate-limits) — limits that apply while paging through large result sets.
* [Reconciliation cases: list reconciliation cases](/api-reference/reconciliation-cases/list-reconciliation-cases) and [Payment intents: list payment intents](/api-reference/payment-intents/list-payment-intents) for concrete examples.