# Listas y paginación (/docs/pagination)

## Listas de recursos [#listas-de-recursos]

Pagos, cobros, clientes, beneficiarios y demás se devuelven del **más nuevo al más antiguo**, en páginas:

```json
{
  "data": [ { "id": "pout_01m3sgb0..." }, { "id": "pout_01m3sga9..." } ],
  "has_more": true,
  "next_cursor": "pout_01m3sga9..."
}
```

| Parámetro | Qué hace |
| --- | --- |
| `limit` | Cuántos por página: de 1 a 100. Por defecto 25. |
| `starting_after` | El `next_cursor` de la página anterior. |

Sigue pidiendo mientras `has_more` sea `true`:

```js
let cursor;
do {
  const url = new URL("https://api-sandbox.caibopay.app/v1/payouts");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("starting_after", cursor);
  const page = await fetch(url, { headers: { Authorization: `Bearer ${key}` } }).then((r) => r.json());
  for (const payout of page.data) handle(payout);
  cursor = page.has_more ? page.next_cursor : undefined;
} while (cursor);
```

Un recorrido devuelve **exactamente una vez** cada elemento que existía al empezar, aunque se creen otros mientras paginas.

### Filtros [#filtros]

| Filtro | Ejemplo |
| --- | --- |
| `status` | `?status=completed` |
| `created_after` (incluido) | `?created_after=2026-10-01T00:00:00Z` |
| `created_before` (excluido) | `?created_before=2026-11-01T00:00:00Z` |
| Relaciones | `?beneficiary_id=ben_…`, `?customer_id=cus_…`, `?funding_account_id=fa_…` |

- Los filtros se combinan con **Y**.
- Las fechas van en RFC 3339. Codifica el `+` de una zona horaria como `%2B`.
- Un valor que el filtro no admite responde `400` con `param` igual al nombre del filtro.
- Un id con buena forma que no es tuyo devuelve una lista vacía.

## Registros: eventos y movimientos [#registros-eventos-y-movimientos]

`GET /v1/events` y `GET /v1/balances/{currency}/entries` se paginan con `after`, y nunca saltan ni repiten. Los eventos se leen del **más antiguo al más nuevo**; los movimientos del saldo, del **más nuevo al más antiguo**.

| Parámetro | Qué hace |
| --- | --- |
| `limit` | De 1 a 100. Por defecto 50. |
| `after` | El `next_cursor` de tu última lectura. |

En los eventos, `next_cursor` viene siempre, también en una página vacía. Guárdalo y vuelve a consultar desde ahí: así nunca te saltas un evento. Ver [Eventos](/docs/events).