# Pagination

Several Ripple Payments Direct 2.0 API endpoints return paginated results when a list could contain many records. The API uses two pagination styles depending on the endpoint:

- **Token-based pagination** for identities, financial instruments, and payment search. The response includes an opaque `nextToken` value that you pass to retrieve the next page.
- **Offset-based pagination** for ledger transactions. You specify a starting record index (`offset`) and the number of records to return (`page-size`).


The table below summarizes which style applies to each paginated endpoint.

| Endpoint | Style | Page size parameter | Default | Maximum |
|  --- | --- | --- | --- | --- |
| `GET /v3/identities` | Token-based | `limit` | 10 | 100 |
| `GET /v3/identities/{identity-id}/financial-instruments` | Token-based | `limit` | 10 | 100 |
| `POST /v3/payments/filter` | Token-based (request body) | `page.size` | 20 | 100 |
| `GET /v2/ledger-transactions` | Offset-based | `page-size` | 25 | 50 |


## Token-based pagination

Token-based pagination uses an opaque string token to mark your position in a result set. When the API returns a `nextToken` in the response, more results are available. When `nextToken` is absent, you have reached the last page.

Tokens are opaque and may change between releases. Do not attempt to decode, parse, or construct token values.

### Identities and financial instruments

For `GET /v3/identities` and `GET /v3/identities/{identity-id}/financial-instruments`, pass pagination parameters as query parameters.

**Request parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `limit` | integer | No | Maximum number of records to return. Default is 10, maximum is 100. |
| `next-token` | string | No | Opaque token returned by the previous response. Omit this parameter to start from the beginning. |


**Example: First page**


```bash
curl -X GET "https://{base-url}/v3/identities?limit=25" \
  -H "Authorization: Bearer <access_token>"
```

**Example response (more pages available):**


```json
{
  "data": [
    { "identityId": "abc123", "identityType": "INDIVIDUAL", "..." },
    { "..." }
  ],
  "nextToken": "eyJrZXkxIjoidmFsdWUifQ=="
}
```

**Example: Subsequent page**


```bash
curl -X GET "https://{base-url}/v3/identities?limit=25&next-token=eyJrZXkxIjoidmFsdWUifQ==" \
  -H "Authorization: Bearer <access_token>"
```

When the response does not include a `nextToken` field, you have retrieved all available records.

### Payment search

The `POST /v3/payments/filter` endpoint uses token-based pagination, but the pagination parameters are passed in the **request body** rather than as query parameters.

**Request body pagination fields:**

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `page.size` | integer | No | Number of payments to return per page. Default is 20, maximum is 100. |
| `page.lastPageToken` | string | No | Token returned in the previous response. Omit to retrieve the first page. |


**Example: First page**


```bash
curl -X POST "https://{base-url}/v3/payments/filter" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "paymentStates": ["COMPLETED"]
    },
    "sort": {
      "sortField": "CREATED_AT",
      "sortDirection": "DESC"
    },
    "page": {
      "size": 20
    }
  }'
```

**Example response (more pages available):**


```json
{
  "data": [ { "..." } ],
  "filter": { "..." },
  "sort": { "..." },
  "page": {
    "size": 20,
    "lastPageToken": "eyJsYXN0SWQiOiJhYmMxMjMifQ=="
  }
}
```

**Example: Subsequent page**

Include the `lastPageToken` value from the previous response in the next request body:


```json
{
  "page": {
    "size": 20,
    "lastPageToken": "eyJsYXN0SWQiOiJhYmMxMjMifQ=="
  }
}
```

When the response does not include a `page.lastPageToken` field, you have retrieved all matching payments.

## Offset-based pagination

The `GET /v2/ledger-transactions` endpoint uses offset-based pagination. You control the result window with two parameters: `page-size` (how many records to return) and `offset` (how many records to skip).

**Request parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `page-size` | integer | Yes | Number of records to return. Default is 25, maximum is 50. |
| `offset` | integer | No | Number of records to skip before returning results. Default is 0 (start from the beginning). |


The response includes a `total` field with the overall count of matching records. Use `total`, `pageSize`, and `pageElements` to determine whether additional pages exist.

**Response fields:**

| Field | Type | Description |
|  --- | --- | --- |
| `total` | integer | Total number of records matching the request filters. |
| `pageSize` | integer | Number of records requested per page (echoes the `page-size` parameter). |
| `pageElements` | integer | Number of records actually returned in this response. |
| `offset` | integer | Number of records skipped (echoes the `offset` parameter). |


**Example: First page**


```bash
curl -X GET "https://{base-url}/v2/ledger-transactions?currency=USD&start-dttm=2026-01-01T00:00:00Z&end-dttm=2026-01-31T23:59:59Z&page-size=25" \
  -H "Authorization: Bearer <access_token>"
```

**Example response:**


```json
{
  "offset": 0,
  "pageSize": 25,
  "pageElements": 25,
  "total": 83,
  "statementTransactions": [ { "..." } ]
}
```

**Example: Second page**

With `total=83` and `pageSize=25`, the second page starts at `offset=25`:


```bash
curl -X GET "https://{base-url}/v2/ledger-transactions?currency=USD&start-dttm=2026-01-01T00:00:00Z&end-dttm=2026-01-31T23:59:59Z&page-size=25&offset=25" \
  -H "Authorization: Bearer <access_token>"
```

You have retrieved all records when `offset + pageElements >= total`.

## Best practices

**Use the maximum page size for bulk retrieval.** When your goal is to retrieve all records (for example, for reconciliation), set `limit` or `page-size` to the maximum allowed value to minimize the number of requests.

**Check for the absence of `nextToken`, not its value.** For token-based endpoints, the correct signal that you have reached the last page is the absence of `nextToken` (or `page.lastPageToken`) in the response, not a specific token value.

**Do not modify or construct tokens.** Tokens are opaque. Building logic that parses or concatenates token values will break when the token format changes.

**Account for records added during retrieval.** Offset-based pagination over an actively changing result set can produce gaps or duplicates. For ledger transactions, use a fixed time range (`start-dttm` and `end-dttm`) to ensure the result set does not change while you paginate through it.

**Do not cache tokens across sessions.** Tokens are only valid for the session in which they were issued. Always start a fresh pagination sequence for a new retrieval job.