ShiwakeDocs

Pagination

Cursor-based pagination using keyset cursors over every list endpoint.

Shiwake uses cursor-based (keyset) pagination on every list endpoint. Cursors are opaque strings returned by the server that encode a position in the underlying index. They are stable under concurrent writes: new entries appearing at the "head" of the list never cause a cursor to skip rows or return duplicates.

Request parameters

Every list endpoint accepts the same two query parameters:

Prop

Type

Some endpoints accept additional filters (e.g. accountType, from, to, status): see the individual resource pages.

Response shape

Every list response includes a next_cursor field alongside the result array. When next_cursor is null you have reached the end of the result set.

{
  "code": 200,
  "message": "Retrieved successfully",
  "data": {
    "accounts": [ /* ... */ ],
    "next_cursor": "CLIENT-42|acc_01HZ..."
  }
}

Cursor formats

Cursors are opaque to clients (do not parse or fabricate them) but for reference, the engine uses two formats depending on the natural sort order of the collection:

EndpointSort orderCursor format
GET /ledger/accountscode ascending, id tiebreakercode|id
GET /ledger/journal-entriespostedAt descending, id tiebreakerpostedAt|id (ISO 8601)
GET /ledger/accounts/{id}/transactionspostedAt descending, id tiebreakerpostedAt|id
GET /ledger/accounts/{id}/holdscreatedAt descending, id tiebreakercreatedAt|id

Treat cursors as opaque. The format may change in a future version; client code that parses them will break.

Iterating a full result set

To walk an entire collection, pass each next_cursor back to the server until it returns null.

string? cursor = null;
var allAccounts = new List<Account>();

do
{
    var page = await ledger.ListAccountsAsync(cursor: cursor, size: 200);
    allAccounts.AddRange(page.Accounts);
    cursor = page.NextCursor;
} while (!string.IsNullOrEmpty(cursor));

URL-encode the cursor when constructing a request manually. The | character is technically reserved. The SDK does this for you.

Choosing a page size

  • Interactive UIs: 20–50 per page keeps latency low.
  • Backfills and exports: use the maximum of 200 to minimize round trips.
  • Real-time tailing: poll with a small size (e.g. 20) and no cursor to always fetch the most recent rows; walk backwards with cursors only when you need history.

Consistency guarantees

Cursors are stable against concurrent inserts. Because each cursor encodes a specific (key, id) tuple and the server filters with strict inequality, a row inserted after you began paginating either:

  • Appears as a new row ahead of your cursor (for descending sorts), which you will not see until you restart iteration, or
  • Appears in a page you have already fetched (impossible: inserts can't retroactively change history).

Deletions similarly do not cause page shifts, because cursors index by id rather than by row position.

Edit on GitHub

Last updated on

On this page