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:
| Endpoint | Sort order | Cursor format |
|---|---|---|
GET /ledger/accounts | code ascending, id tiebreaker | code|id |
GET /ledger/journal-entries | postedAt descending, id tiebreaker | postedAt|id (ISO 8601) |
GET /ledger/accounts/{id}/transactions | postedAt descending, id tiebreaker | postedAt|id |
GET /ledger/accounts/{id}/holds | createdAt descending, id tiebreaker | createdAt|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.
Last updated on