Pagination

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 order_by parameter (defaults to id ascending).

Query Parameters

Parameter	Type	Default	Description
limit	number	10	Items per page (1–100)
next_cursor	string	—	Cursor for the next page
prev_cursor	string	—	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.
prev_cursor	Pass this as prev_cursor to go back. null on the first page.
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.getInvoices({ 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.getInvoices({
    limit: 20,
    next_cursor: page1.pagination.next_cursor,
  });
}

Basic curlbash

Copy

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

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

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.