Pagination

List endpoints use one of two pagination styles, picked per endpoint based on what makes sense.

Offset pagination (default)

Standard page + limit query params:

GET /api/customers?page=2&limit=50

Response includes totals:

{
  "data": [...],
  "total": 1247,
  "page": 2,
  "limit": 50,
  "meta": { "pages": 25 }
}

• Default limit: 20
• Max limit: varies by endpoint, usually 100 or 1000 — endpoint reference documents the cap
• page is 1-indexed.

Use offset pagination when:

• You need a page number UI ("Page 3 of 25").
• The dataset is bounded and stable (settings, members, rules).

Cursor pagination (large or append-only feeds)

For high-volume time-ordered endpoints (verification attempts, alert feeds, webhook deliveries), we use cursor-based pagination:

GET /api/identity/attempts?limit=50

Response:

{
  "rows": [...],
  "nextCursor": "2026-05-24T10:15:22.481Z"
}

Then fetch the next page by passing the cursor back:

GET /api/identity/attempts?cursor=2026-05-24T10:15:22.481Z&limit=50

When nextCursor is null, you've reached the end.

Use cursor pagination when:

• The list is unbounded (audit logs, attempts, webhooks).
• Items are added at the top — page numbers would shift under you.
• You're tailing the latest activity in near-real-time.

Filters

All list endpoints accept query-param filters documented per-endpoint. Common ones: