Pagination

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

Parameter	Type	Notes
`limit`	number	Items per page. Minimum `1`, maximum `100`. The default depends on the endpoint.
`after`	string	Cursor to fetch the page after a position. Use the `next` cursor from a previous response.
`before`	string	Cursor to fetch the page before a position. Use the `previous` cursor from a previous response.
`orderBy`	string	Field to sort by (endpoint-specific).
`orderDirection`	string	`ASC` or `DESC`.
`includeCursor`	boolean	Include the cursor item itself in the results.

limit is capped at 100 items per page across list endpoints (cursor-based, offset-based, and legacy page-based). Requesting a limit greater than 100 returns a 422 validation error, so page through large collections with multiple requests instead of raising limit.

Response envelope

Cursor-based list endpoints return a consistent envelope:

{
  "data": [ /* array of items */ ],
  "next": "eyJpZCI6IjY1...",
  "previous": null,
  "totalCount": 1240,
  "totalCountCapped": false
}

Field	Description
`data`	The array of items for the current page.
`next`	Cursor for the next page, or `null` if this is the last page.
`previous`	Cursor for the previous page, or `null` if this is the first page.
`totalCount`	Total matching items, counted up to a maximum of 50,000.
`totalCountCapped`	`true` 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:

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:

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.

Endpoint	Notes
List all messages	Uses `page` and `limit`.
List all events	Uses `page` and `limit`.
Retrieve subscriber notifications	v1 feed endpoint. Uses `page` and `limit`.

Overview - REST API capabilities and conventions
Rate Limiting - Stay within request limits while paging
Search subscribers - Filter and paginate subscriber results

Getting Started

Notification delivery

Agents

Data

Workflows & content

Platform & channels

Query parameters

Response envelope

Cursor-based endpoints

Fetch all pages

​Query parameters

​Response envelope

​Cursor-based endpoints

​Fetch all pages

​Legacy page-based pagination

​Related documentation

Query parameters

Response envelope

Cursor-based endpoints

Fetch all pages

Legacy page-based pagination

Related documentation