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.

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.

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 for retry guidance.