Pagination

Summary

Core public list operations return a data array and meta object:

{
  "data": [],
  "meta": {
    "cursor": null,
    "hasPreviousPage": false,
    "hasNextPage": false
  }
}

This example is an empty result. A full page can provide a cursor string for the next request. Pass that string back unchanged; the actual format varies by resource and sort.

Capabilities

Resource Limits

The public OpenAPI schema does not promise a default page size for these three operations. Set pageSize explicitly when you need a stable batch size.

Prerequisites

To use pagination, you need API access to Eigenn resources and must be able to supply authentication with your requests. Prepare a stable set of filter and sort parameters before starting a pagination run.

Concepts

No Total Count

Customer, invoice, and transaction page metadata does not include a total count or maximum page number. Design progress reporting around processed records and the next cursor, not a precomputed total.

Keep a Stable Query

If you change the filters but reuse a cursor, the API can skip or repeat records. Keep these values stable across a pagination run:

• search query
• date range
• statuses
• categories and tags
• customer or account filters
• sort field and direction
• page size

For a large export, choose a bounded date range and a stable sort. Records can still change during the export. Make the destination upsert by Eigenn resource ID.

Array Parameters

Some list operations accept arrays, such as customer IDs, statuses, tags, categories, or accounts. Use the serialization generated by the SDK or the current OpenAPI explorer. Do not invent a comma-separated format when your HTTP client can follow the contract.

Workflow

Request the Next Page

1. Send the first request without a cursor.
2. Process the returned data.
3. If meta.hasNextPage is true, send meta.cursor as the next request's cursor.
4. Preserve every filter and sort setting.
5. Stop when meta.hasNextPage is false or the cursor is null.

Treat the cursor as opaque. Do not decode, change, increment, or persist assumptions about its format.

Behavior specification

Retry a Page

A page request is a read. You can send it again after a transient failure. Reuse the same cursor and the same filters. Do not advance the saved cursor until you store the page successfully.

The result is not a frozen snapshot. Inserts, deletions, or changes to sort values can alter a repeated page. Deduplicate by resource ID and restart without a cursor when changing the query.

End of a Collection

These list queries set hasNextPage when the number of returned records equals pageSize; they do not fetch an extra record to prove another page exists. If the collection ends on a full page, the next request can return an empty data array and hasNextPage: false. Treat this as normal completion.

An empty first result also has cursor: null and hasNextPage: false. Do not require a cursor for an empty or final page. Values outside the documented page-size range fail request validation rather than being silently clamped. For a nonterminal response with a missing or unchanged cursor, stop and report the inconsistency instead of looping forever.

Diagrams

Screenshots

Not applicable: this page describes an API or a non-visual workflow rather than an application screen.

Verification

1. Use a fixed local dataset and request the first page without a cursor. Check data and all three meta fields; allow a null cursor on an empty or final page.
2. Request the next page using the returned cursor, keeping all filters and sorting identical. Confirm that new data is returned, and meta.hasNextPage updates appropriately.
3. Retry with the same cursor and filters against unchanged fixtures and check the returned IDs. Separately change the dataset and verify the client tolerates shifted results without duplicating stored records.
4. Exercise empty, partial-final-page, and exact-page-multiple datasets. Confirm the extra empty page completes normally. Change a filter and confirm the client discards its old cursor.
5. Request zero and above-maximum page sizes and verify a validation failure. Test a missing or repeated next cursor in the client to confirm it cannot loop forever.
6. Confirm that no total count is present in the meta object for customer, invoice, and transaction endpoints.

Related

Related Pages

• Customers API
• Invoices API
• Transactions API
• Rate Limits