Pagination

Outcome

Traverse large collections without duplicate or skipped pages.

Prerequisites

A list endpoint and stable query/order parameters.

You'll use

limit, next_cursor, prev_cursor, and pagination metadata.

All list endpoints return paginated results using cursor-based pagination. This approach is more efficient than offset-based pagination, especially for large datasets.

How It Works

1. Request a page with an optional limit
2. The response includes a pagination object with cursors
3. Pass next_cursor to get the next page, prev_cursor to go back

Results are ordered by the endpoint’s default order unless you override it with order_by.

Cursors are opaque tokens. Treat them as read-only values from the API. Do not parse them, construct them manually, or reuse them with a different order_by value. Changing ordering means restarting pagination from the first page.

Query Parameters

Parameter	Type	Default	Description
limit	number	10	Items per page (1–100)
next_cursor	string	—	Opaque cursor for the next page
prev_cursor	string	—	Opaque cursor for the previous page
include_total_count	boolean	true	Include total count in response

Response Format

Every list endpoint returns this structure:

{
  "data": [ ... ],
  "pagination": {
    "total": 84,
    "next_cursor": "inv_def456",
    "prev_cursor": null,
    "has_more": true
  }
}

Field	Description
total	Total number of matching items (or -1 if include_total_count=false)
next_cursor	Pass this as next_cursor to get the next page. null if no more results. Valid only for the same effective ordering.
prev_cursor	Pass this as prev_cursor to go back. null on the first page. Valid only for the same effective ordering.
has_more	true if there are more results after this page

Walking Through Pages

To iterate through all results, keep requesting pages until has_more is false:

Basic sdktypescript

Copy

// title: SDK
// First page
const page1 = await sdk.invoices.list({ limit: 20 });

console.log(page1.data); // Invoice[]
console.log(page1.pagination.has_more); // true

// Next page using cursor
if (page1.pagination.next_cursor) {
  const page2 = await sdk.invoices.list({
    limit: 20,
    next_cursor: page1.pagination.next_cursor,
  });
}

Personalize locallyChecked with SDK v4.0.0

Basic curlbash

Copy

# title: cURL
curl "https://eu.spaceinvoices.com/invoices?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Entity-Id: ent_123"

# Next page using cursor from response
curl "https://eu.spaceinvoices.com/invoices?limit=20&next_cursor=CURSOR_FROM_RESPONSE" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Entity-Id: ent_123"

Personalize locally

Performance Tip

The total count requires an extra database query. For large datasets where you don’t need the exact count, disable it:

?include_total_count=false

When disabled, pagination.total returns -1 but pagination still works normally via has_more and cursors.