---
url: /docs/learn/pagination.md
description: >-
  List endpoints return every match by default. Pass any pagination parameter to
  switch to a paginated envelope.
---

Most list endpoints (customers, payins, payouts, payables, and transfers) share the same pagination and filtering convention.

## Pagination is opt-in

Call a list endpoint with no pagination parameters and you get every matching row back as a plain array, uncapped. Pass `limit`, `starting_after`, or `ending_before` and the response switches to a paginated envelope instead:

```json
{
  "data": [ ... ],
  "pagination": {
    "has_more": true,
    "next_page": "pi_000000000000",
    "prev_page": null
  }
}
```

[Transfers](/docs/transfers) is the one exception: it always returns the paginated envelope, even with no parameters.

## Query parameters

| Param | Values | Notes |
| --- | --- | --- |
| `limit` | `10`, `50`, `100`, `200`, `500`, `1000` | Page size. If you paginate but omit `limit`, the default is 100 for customers and 10 for payins, payouts, transfers, and payables. Pass `limit` explicitly if you want a consistent page size across resources. |
| `starting_after` | an object ID (e.g. `pi_123`) | Returns the page after this object. |
| `ending_before` | an object ID (e.g. `pi_123`) | Returns the page before this object. |
| `offset` | accepted, not applied | Pagination is cursor-based. Use `starting_after` or `ending_before` to page; `offset` has no effect. |

## Walking pages

Results are always returned newest first, whichever cursor you use. `next_page` and `prev_page` are object IDs, not page numbers, so feed them straight back in as `starting_after` or `ending_before` on your next call rather than incrementing anything yourself.

| Field | Meaning |
| --- | --- |
| `has_more` | `true` if there are more rows past this page. |
| `next_page` | The ID to pass as `starting_after` to get the next page. `null` when `has_more` is `false`. |
| `prev_page` | Echoes back whichever of `starting_after` or `ending_before` you passed in. |

## Sort order

Results are always ordered newest first, by creation time. There is no `sort` or `order` parameter on any list endpoint.

## Filters

Combine pagination with the filters each resource supports:

| Resource | Filters |
| --- | --- |
| [Customers](/docs/learn/customers) | `full_name`, `customer_name`, `status`, `customer_id`, `bank_account_id`, `country` |
| [Payins](/docs/payins) / [Payouts](/docs/payouts) | `customer_id`, `status`, `customer_name`, `bank_account_id`, `country`, `payment_method`, `network`, `token` |
| [Payables](/docs/payables) | `status`, `customer_id` |
| [Bank accounts](/docs/bank-accounts) | `status`, `type`, `name`, `bank_account_id`, `country` |

`customer_name` and `full_name` do a partial, case-insensitive match. Every other filter is an exact match.

Bank accounts are only listed per customer (`GET /instances/{instance_id}/customers/{customer_id}/bank-accounts`) and only support filtering, not pagination: the response is always a plain array.

## Related

* [Customers](/docs/learn/customers)
* [Payables](/docs/payables)