Use Cursor-Based Pagination

Our API uses cursor-based pagination to handle large collections of data efficiently for alpha index endpoints.

How It Works

Each paginated response includes the results and pagination metadata:

{  
  "items": [...],  
  "has_more": true,  
  "next_cursor": "eyJpZCI6MTAwfQ=="  
}

Making Requests

Initial Request

Make your first request without a cursor:

GET /api/external/v2/customer_invoices

You can specify the number of results per page using the limit parameter:

GET /api/external/v2/customer_invoices?limit=50

Note: The default limit is 20. Maximum limit varies by endpoint - refer to the specific endpoint documentation.

Subsequent Pages

To get the next page, use the next_cursor value from the previous response:

GET /api/external/v2/customer_invoices?cursor=eyJpZCI6MTAwfQ==&limit=50

Paginating Filtered Results

The cursor only encodes position in the result set — it does not store filter state. When paginating a filtered request, you must re-send the same filter (and sort, if used) parameters on every subsequent request alongside the cursor.

# Page 1
GET /api/external/v2/customer_invoices?filter=[{"field":"status","operator":"eq","value":"draft"}]&limit=50

# Page 2 — filters must be repeated
GET /api/external/v2/customer_invoices?filter=[{"field":"status","operator":"eq","value":"draft"}]&limit=50&cursor=eyJpZCI6MTAwfQ==

Omitting the filters on page 2+ will return unfiltered results from the cursor position.

Understanding the Response

items: Contains the current page of results
has_more: Indicates if more results are available
next_cursor: Used to retrieve the next page
- Present and non-empty when more results exist
- null when you've reached the end

Important Notes

Cursors are temporary and should not be stored for long-term use
Invalid cursors will result in a 400 Bad Request response
Using a consistent limit value across requests is recommended
Filters and sort parameters must be re-sent on every paginated request — the cursor does not remember them
Check each endpoint's documentation for its specific maximum limit