Pagination

Overview

All list endpoints return results in pages. The default page size is 50 items, configurable up to 200 via the limit parameter.

Cursor Pagination

Cursor pagination is the default. It uses an opaque, base64-encoded cursor token to track position.

First page:

GET /api/external/v2/build/deals?limit=10

Response:

{
  "data": [...],
  "pagination": {
    "total": 142,
    "limit": 10,
    "cursor": null,
    "has_more": true,
    "next_cursor": "eyJpZCI6IDEwfQ=="
  }
}

Next page:

GET /api/external/v2/build/deals?limit=10&cursor=eyJpZCI6IDEwfQ==

Continue passing next_cursor as cursor until has_more is false.

Note: Cursor pagination is mutually exclusive with the sort parameter. If you need sorted results, use offset pagination.

Offset Pagination

When a sort parameter is provided, the API uses offset pagination:

GET /api/external/v2/build/deals?sort=-created_at&limit=10&offset=20

Response:

{
  "data": [...],
  "pagination": {
    "total": 142,
    "limit": 10,
    "offset": 20,
    "has_more": true
  }
}

Offset pagination starts at offset=0. To get the next page, add limit to the current offset.

Caution: Offset pagination can skip or duplicate items if rows are inserted or deleted between requests. For reliable bulk sync, use cursor pagination.

Limits