# Pagination

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

URL: https://docs.shiwake.app/docs/api/pagination



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 [#request-parameters]

Every list endpoint accepts the same two query parameters:

<TypeTable
  type="{
  cursor: { type: &#x22;string&#x22;, default: &#x22;null&#x22;, description: &#x22;Cursor returned by the previous page. Omit for the first page.&#x22; },
  size: { type: &#x22;int&#x22;, default: &#x22;50&#x22;, description: <>Page size, clamped to <code>[1, 200]</code>. Values outside the range silently snap to <code>50</code>.</> },
}"
/>

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

Response shape [#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.

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

Cursor formats [#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`           |

<Callout type="info">
  Treat cursors as opaque. The format may change in a future version; client
  code that parses them will break.
</Callout>

Iterating a full result set [#iterating-a-full-result-set]

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

<CodeBlockTabs defaultValue="csharp">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="csharp">
      C# (SDK)
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="csharp">
    ```csharp
    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));
    ```
  </CodeBlockTab>

  <CodeBlockTab value="curl">
    ```bash
    # First page
    curl -sS "https://api.shiwake.example.com/api/v1/ledger/accounts?size=200" \
      -H "X-Api-Key: sk_live_..."

    # Subsequent pages: paste the next_cursor from the previous response
    curl -sS "https://api.shiwake.example.com/api/v1/ledger/accounts?size=200&cursor=CLIENT-42%7Cacc_01HZ..." \
      -H "X-Api-Key: sk_live_..."
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Callout type="warn">
  URL-encode the cursor when constructing a request manually. The `|`
  character is technically reserved. The SDK does this for you.
</Callout>

Choosing a page size [#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 [#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.
