ContextQMD
Back to Novu

Pagination

docs/api-reference/pagination.mdx

3.18.03.9 KB
Original Source

List endpoints return results in pages so you can retrieve large collections efficiently. Novu uses cursor-based pagination as the standard for list endpoints. Pass an opaque cursor to walk forward or backward through results without skipping or duplicating items as your data changes.

A small number of legacy endpoints still use page-based pagination with page and limit. For new integrations, use the cursor-based endpoints listed below.

Query parameters

ParameterTypeNotes
limitnumberItems per page.
afterstringCursor to fetch the page after a position. Use the next cursor from a previous response.
beforestringCursor to fetch the page before a position. Use the previous cursor from a previous response.
orderBystringField to sort by (endpoint-specific).
orderDirectionstringASC or DESC.
includeCursorbooleanInclude the cursor item itself in the results.

Response envelope

Cursor-based list endpoints return a consistent envelope:

json
{
  "data": [ /* array of items */ ],
  "next": "eyJpZCI6IjY1...",
  "previous": null,
  "totalCount": 1240,
  "totalCountCapped": false
}
FieldDescription
dataThe array of items for the current page.
nextCursor for the next page, or null if this is the last page.
previousCursor for the previous page, or null if this is the first page.
totalCountTotal matching items, counted up to a maximum of 50,000.
totalCountCappedtrue when more than 50,000 results match and totalCount is capped.

To page forward, pass the next cursor as after on the following request. Stop when next is null:

bash
curl -G https://api.novu.co/v2/subscribers \
  --header 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
  --data-urlencode 'limit=50' \
  --data-urlencode 'after=eyJpZCI6IjY1...'

Cursor-based endpoints

These endpoints use cursor pagination:

Fetch all pages

This example walks every page of a cursor-based list with the TypeScript SDK until there are no more results:

javascript
import { Novu } from '@novu/api';

const novu = new Novu({ secretKey: process.env.NOVU_SECRET_KEY });

async function listAllSubscribers() {
  const all = [];
  let after;

  do {
    const { result } = await novu.subscribers.list({ limit: 100, after });
    all.push(...result.data);
    after = result.next ?? undefined;
  } while (after);

  return all;
}

Legacy page-based pagination

A few older endpoints still accept page and limit instead of cursors. They return page, pageSize, and hasMore in the response. Prefer the cursor-based alternatives above when both exist.

EndpointNotes
List all messagesUses page and limit.
List all eventsUses page and limit.
Retrieve subscriber notificationsv1 feed endpoint. Uses page and limit.