Cursor Pagination

📘

This article covers:

• What cursor pagination is and how the token works.
• The difference between FIRST, LAST, NEXT, and PREVIOUS.
• How to paginate through a real endpoint step by step.
• Which endpoints support cursor pagination.
• A common error and how to avoid it.

Paginated endpoints use a cursor token to track your position in the result set. The token is generated server-side and passed back in each response. You copy it into your next request to get the next page.

FIRST and LAST do not require a token. NEXT and PREVIOUS do, and the token must come directly from a prior API response. It cannot be constructed manually.

Flow

1. Start from the beginning

GET /api/rest/v1/statistics/tags/{tagID}?cursor.pageRequest=FIRST&cursor.pageSize=20

{
  "result": [...],
  "cursor": {
    "currentPage": "eyJjdXJyIjoiLi4uIn0=",
    "hasNext": true,
    "hasPrevious": false
  }
}

hasPrevious: false, you're at the start. hasNext: true , more pages exist.

2. Get the next page

Copy cursor.currentPage from the response verbatim and pass it back:

GET /api/rest/v1/statistics/tags/{tagID}?cursor.pageRequest=NEXT&cursor.pageSize=20&cursor.currentPage=eyJjdXJyIjoiLi4uIn0=

The server picks up exactly where it left off and returns a new token.

3. Repeat until hasNext: false

That means you've reached the end.

pageRequest Values

Endpoints That Support Cursor Pagination

Common Issue

E900-INVALID_CURSOR_DATA , the token you sent is invalid.

This happens when cursor.currentPage is constructed manually rather than copied from an API response. The token is base64-encoded and serialized internally. Any value not produced by the server will fail to decode and return this error.

If you see this error, confirm that cursor.currentPage is taken directly from a prior response and not generated on your side.