> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kirafin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> How each list endpoint pages its results, and which of the four shapes it returns.

Most list endpoints take a `limit` and return 10 rows when you omit it. There are four shapes, and a missing `pagination` object reads as "no more results".

Read the shape off the response, not off the resource. The table at the end says which endpoint uses which.

## The four shapes

The rows always come back under a key named for the resource — `data`, `payouts`, `recipients`. What changes is what sits beside them.

### An offset object

Takes `limit` and `offset`, and wraps the rows with a `pagination` object.

```json theme={null}
{
  "data": [ ... ],
  "pagination": {
    "total": 214,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}
```

Walk it by adding `limit` to `offset` until `has_more` is `false`. `total` counts the rows matching your filters, not the rows on this page.

### Numbered pages

Takes `limit` and `page`, counting from `1`, and puts the counters at the top level beside the rows.

```json theme={null}
{
  "payouts": [ ... ],
  "page": 1,
  "limit": 10,
  "total": 42,
  "total_pages": 5
}
```

There is no `has_more` here. Stop when `page` reaches `total_pages`.

### A bare array

Takes `limit` and `offset` and returns the rows with nothing around them:

```json theme={null}
[ { "id": "...", "amount": "100.00" } ]
```

No total, no `has_more`. You have reached the end when you get back fewer rows than the `limit` you asked for.

### A total with no paging

Returns every row and a `total`, and takes no `limit`, `offset` or `page`. Sending one changes nothing.

```json theme={null}
{ "recipients": [ ... ], "total": 12 }
```

## The parameters

| Parameter | Range       | Omitted |
| --------- | ----------- | ------- |
| `limit`   | `1`–`100`   | `10`    |
| `offset`  | `0` or more | `0`     |
| `page`    | `1` or more | `1`     |

## Which endpoint uses which

| Endpoint                     | Asks with          | Returns                                                                                       |
| ---------------------------- | ------------------ | --------------------------------------------------------------------------------------------- |
| List users                   | `limit` + `offset` | `pagination` object                                                                           |
| List virtual accounts        | `limit` + `offset` | `pagination` object                                                                           |
| List RFIs                    | `limit` + `offset` | `pagination` object                                                                           |
| List payouts                 | `limit` + `page`   | Top-level counters                                                                            |
| List deposits (all accounts) | `limit` + `page`   | Top-level counters                                                                            |
| List deposits (one account)  | `limit` + `offset` | Bare array. Out-of-range values are silently clamped to the bounds above rather than rejected |
| List recipients              | —                  | `total` only                                                                                  |