> For the complete documentation index, see [llms.txt](https://docs.nullify.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nullify.ai/api-reference/api-reference/pagination.md).

# Pagination

List endpoints use several pagination contracts. Many finding lists accept `limit` and `nextToken`; other endpoints use `page`, `offset`, `cursor`, or `startKey`. Check the individual operation in the [OpenAPI specification](https://docs.nullify.ai/api-reference/api-reference/openapi-spec.md).

## Following nextToken

1. Make the first request without `nextToken`.
2. Process the returned items and retain their stable IDs.
3. If `nextToken` is non-empty, pass it unchanged in the next request, with the same filters and ordering.
4. Stop when the token is empty or absent. A final request can return an empty page even when the previous page supplied a token.

Treat tokens as opaque and URL-encode them. Several Postgres-backed lists encode an **offset**, not a stable position in a snapshot; do not decode, construct, or reuse tokens across endpoints. Inserts, updates, or deletions while paging can produce skipped or repeated rows. Deduplicate by ID and reconcile later when exporting a changing collection.

Many finding endpoints cap `limit` at **100** and reject larger values. Defaults and caps vary by endpoint; a successful request with a smaller limit does not establish the maximum for another resource.

## Example: credential findings

Use `/secrets/credentials/findings` for credentials and `/secrets/sensitivedata/findings` for sensitive data. `/secrets/findings` is a legacy credential-findings alias, not a combined feed for both.

```bash
curl --get 'https://api.<TENANT>.nullify.ai/secrets/credentials/findings' \
  --header "Authorization: Bearer $NULLIFY_TOKEN" \
  --data-urlencode 'githubOwnerId=<OWNER_ID>' \
  --data-urlencode 'limit=50'

# Copy nextToken from the response into NEXT_TOKEN, then request the next page.
curl --get 'https://api.<TENANT>.nullify.ai/secrets/credentials/findings' \
  --header "Authorization: Bearer $NULLIFY_TOKEN" \
  --data-urlencode 'githubOwnerId=<OWNER_ID>' \
  --data-urlencode 'limit=50' \
  --data-urlencode "nextToken=$NEXT_TOKEN"
```

Keep the item-array field from the endpoint's response schema; not every list uses `findings`. See [Authentication](https://docs.nullify.ai/api-reference/api-reference/authentication.md#retries) for retry guidance.
