Pagination | Nuratix Docs

List endpoints support two ways to page through results:

Cursor pagination (recommended). Pass the nextCursor from one response as cursor in the next request. Pages stay stable while new records are created, so you never skip or repeat a record. Use this for syncing, exports and agents.
Page numbers. Pass page and limit. Useful for numbered pages in a UI.

Every list response includes the fields for both.

Cursor Pagination

Request the first page without a cursor, then follow nextCursor until hasMore is false:

curl "https://nuratix.com/api/contacts/v1/list?limit=100" \
  -H "x-api-key: rl_prod_YOUR_API_KEY"

# Response includes: "hasMore": true, "nextCursor": "eyJ0IjoiMjAyNi0xMC0yNVQx..."

curl "https://nuratix.com/api/contacts/v1/list?limit=100&cursor=eyJ0IjoiMjAyNi0xMC0yNVQx..." \
  -H "x-api-key: rl_prod_YOUR_API_KEY"

let cursor = null;
do {
  const url = new URL("https://nuratix.com/api/contacts/v1/list");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);
  const res = await fetch(url, { headers: { "x-api-key": process.env.RELOOP_API_KEY } });
  const page = await res.json();
  for (const contact of page.contacts) handle(contact);
  cursor = page.nextCursor;
} while (cursor);

Field	Type	Description
`hasMore`	`boolean`	Whether more results exist after this page.
`nextCursor`	`string \| null`	Pass as `cursor` to get the next page. `null` on the last page.

Rules:

Treat cursors as opaque strings. Pass them back unchanged; do not build or edit them. An invalid cursor returns 400.
Keep the same filters (and limit, if you like) on every request in a walk. A cursor only marks a position.
When cursor is set, page is ignored. You can start in page mode and switch: every page-mode response also returns a nextCursor.
Results are ordered newest first unless an endpoint says otherwise.
A few endpoints offer alternative sort orders. Cursors only work with the default order; combining cursor with another sort returns 400, and nextCursor is null for those sorts:
- List contacts with suppressed=true (sorted by suppression date).
- List API keys with a sort other than createdAt:desc.
- Campaign recipients with category=clicked (sorted by clicks).

Exceptions

Automations and custom events use page numbers only. They are sorted by last update, which changes when a record is edited, so a cursor would not be stable. These lists are small; fetch them with limit=100.
Agent inbox messages and threads use limit and offset and return a plain array.
Group members (/api/contacts/v1/groups/{group_id}/contacts) are ordered oldest first.

Page Numbers

Query Parameters

Parameter	Type	Default	Max	Description
`page`	`number`	`1`	-	The page number to retrieve (1-indexed).
`limit`	`number`	`20`	`100`	The number of records to return per page.

Example request:

curl "https://nuratix.com/api/contacts/v1/list?page=2&limit=50" \
  -H "x-api-key: rl_prod_YOUR_API_KEY"

Response Structure

Pagination metadata is returned at the root of the JSON response alongside the data array. The exact field names vary by endpoint, but every paginated response includes total, page, and limit.

Contacts

The contacts list endpoint includes additional aggregate counts:

{
  "object": "contact",
  "contacts": [...],
  "total": 120,
  "page": 1,
  "limit": 20,
  "hasMore": true,
  "nextCursor": "eyJ0IjoiMjAyNi0xMC0yNVQx...",
  "totalContacts": 120,
  "subscribedContacts": 100,
  "unsubscribedContacts": 20,
  "event": "contact.list"
}

Field	Type	Description
`contacts`	`array`	The list of contact objects for the current page.
`total`	`number`	Total number of contacts matching the query.
`page`	`number`	The current page number.
`limit`	`number`	The page size used for this request.
`totalContacts`	`number`	Total contacts in the organization.
`subscribedContacts`	`number`	Number of contacts with an active subscription.
`unsubscribedContacts`	`number`	Number of contacts who have unsubscribed.

Templates

{
  "templates": [...],
  "total": 45,
  "page": 1,
  "limit": 20,
  "hasMore": true,
  "nextCursor": "eyJ0IjoiMjAyNi0xMC0yNVQx...",
  "event": "template.list"
}

Field	Type	Description
`templates`	`array`	The list of template objects for the current page.
`total`	`number`	Total number of templates matching the query.
`page`	`number`	The current page number.
`limit`	`number`	The page size used for this request.

Calculating Total Pages

Use the total and limit fields to calculate the number of pages:

const totalPages = Math.ceil(response.total / response.limit);
const hasNextPage = response.page < totalPages;