Working with Pagination

Pagination Strategies

Aelix collection endpoints support two pagination styles. Check the API reference to see which style a specific endpoint uses.

Cursor-Based Pagination (Recommended)

Cursor pagination is stable under concurrent writes and is the recommended approach for production integrations. The response includes a next_cursor value to pass in your next request:

// First page
GET /v1/transactions?limit=50

{
"data": [...],
"pagination": {
"next_cursor": "cur_ZmlyZXN0b25l",
"has_more": true,
"total": 2847
}
}

// Next page
GET /v1/transactions?limit=50&cursor=cur_ZmlyZXN0b25l

Iterate until has_more is false:

async function fetchAll(endpoint) {
const results = [];
let cursor = null;

do {
const url = cursor
? `${endpoint}?limit=100&cursor=${cursor}`
: `${endpoint}?limit=100`;
const page = await apiFetch(url);
results.push(...page.data);
cursor = page.pagination.has_more ? page.pagination.next_cursor : null;
} while (cursor);

return results;
}

Offset Pagination (Legacy Endpoints)

Some older endpoints use offset/limit pagination:

GET /v1/accounts?offset=0&limit=25
GET /v1/accounts?offset=25&limit=25

Avoid using offset pagination for large datasets — it becomes inconsistent when records are added or removed between pages. Migrate to cursor-based endpoints where available.

Filtering and Sorting

Most collection endpoints support filtering to reduce result sets before paginating:

GET /v1/transactions
?account_id=acc_123
&from=2025-01-01T00:00:00Z
&to=2025-03-31T23:59:59Z
&type=debit
&sort=created_at:desc
&limit=50