# Paginación

> Cómo pagina cada ruta de lista de la API de watsi — offset, cursor o página — con los parámetros, campos de respuesta y límites reales de cada una.

Source: https://docs.watsi.ai/guides/pagination

Las rutas de lista no paginan todas igual: cada una usa el estilo que mejor encaja con sus datos. La tabla de abajo se genera de los esquemas de cada ruta, así que dice exactamente qué parámetros acepta y qué campos devuelve.

| Ruta | Estilo | Parámetros | Campos de posición | limit (defecto / máx.) |
| --- | --- | --- | --- | --- |
| `GET agents/learned-answers` | una página | `limit` | — | — / 200 |
| `GET agents/versions` | cursor | `limit`, `before` | `nextCursor` | — / 50 |
| `GET analytics/at-risk` | una página | `limit` | `total` | — / 100 |
| `GET analytics/booking-failures` | una página | `limit` | `total` | 20 / 100 |
| `GET analytics/content` | una página | `limit` | — | — / 50 |
| `GET analytics/lead-attribution` | una página | `limit` | `total` | — / 500 |
| `GET analytics/meta-ads` | una página | `limit` | — | — / 100 |
| `GET appointments/list` | una página | `limit` | `total` | 50 / 100 |
| `GET automations/comment-rules/activity` | cursor | `limit`, `cursor` | `nextCursor` | — / 100 |
| `GET billing/payment-history` | offset | `limit`, `offset` | `total`, `limit`, `offset` | 20 / 100 |
| `GET campaigns/list` | página | `limit`, `page` | `total`, `limit` | — / 100 |
| `GET campaigns/recipients` | página | `limit`, `page` | `total`, `limit` | — / 200 |
| `GET contacts/list` | offset | `limit`, `offset` | `total`, `limit`, `offset` | 50 / 100 |
| `GET contacts/pending-merges` | una página | `limit` | — | 25 / 100 |
| `GET conversations/list` | cursor | `limit`, `cursor`, `before` | `total`, `hasMore`, `nextCursor`, `totalIsCapped` | 20 / 100 |
| `GET leads` | una página | `limit` | `total` | — / 100 |
| `GET meetings/search` | cursor | `limit`, `cursor` | `nextCursor` | — / 100 |
| `GET meetings/upcoming` | cursor | `limit`, `cursor` | `nextCursor` | — / 100 |
| `GET messages/search` | offset | `limit`, `offset` | `total`, `total_is_capped` | 30 / 100 |
| `GET quotes/list` | offset | `limit`, `offset` | `total` | 20 / 50 |
| `GET quotes/quotable-properties` | offset | `limit`, `offset` | `total` | 20 / 50 |
| `GET resources/list` | página | `limit`, `page` | `pagination` | 50 / 100 |
| `GET templates/search` | una página | `limit` | `total` | 20 / 50 |
| `GET tickets` | una página | `limit` | `total` | — / 100 |
| `GET voice/calls` | una página | `limit` | `count` | — / — |

## Offset: `limit` + `offset`

`contacts/list`, `messages/search` y `billing/payment-history`. Pide `limit` filas a partir de `offset` y usa `total` para saber cuándo parar.

```bash
curl "https://api.watsi.ai/v1/actions/contacts/list?limit=100&offset=200" \
  -H "Authorization: Bearer $WATSI_API_KEY"
```

```json
{ "data": [], "total": 248, "limit": 100, "offset": 200 }
```

Sigue mientras `offset + data.length < total`. Si los datos cambian entre páginas (llega un contacto nuevo), una fila puede repetirse o saltarse; para una exportación completa, deduplica por `id`.

`messages/search` trae además `total_is_capped`: cuando es `true`, `total` está topado y hay más coincidencias de las que dice.

## Cursor: `cursor`

`conversations/list` ordena por actividad más reciente y pagina hacia atrás en el tiempo; las conversaciones que todavía no tienen ningún mensaje van al final, de la más nueva a la más vieja. Cada página trae `nextCursor`: pásalo tal cual en `cursor`, con los mismos filtros, y sigue mientras `hasMore` sea `true`. Es `null` en la última página.

```bash
# Primera página
curl "https://api.watsi.ai/v1/actions/conversations/list?limit=50" \
  -H "Authorization: Bearer $WATSI_API_KEY"

# Siguiente página
curl "https://api.watsi.ai/v1/actions/conversations/list?limit=50&cursor=activity:2026-10-29T21:14:03.000Z" \
  -H "Authorization: Bearer $WATSI_API_KEY"
```

```javascript Node.js
async function allConversations(apiKey) {
  const rows = []
  let cursor
  while (true) {
    const url = new URL('https://api.watsi.ai/v1/actions/conversations/list')
    url.searchParams.set('limit', '100')
    if (cursor) url.searchParams.set('cursor', cursor)
    const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } })
    if (!res.ok) throw new Error(`watsi ${res.status}: ${await res.text()}`)
    const page = await res.json()
    rows.push(...page.data)
    if (!page.nextCursor) return rows
    cursor = page.nextCursor
  }
}
```

- `nextCursor` sirve también con `dateField=created`; un cursor de un orden no vale para el otro y responde `400`.
- `before` sigue aceptándose (el `last_message_at` de la última fila, o su `created_at` con `dateField=created`), pero no puede pasar de una conversación sin mensajes, que no tiene `last_message_at`. Usa `cursor`.
- Las conversaciones de prueba del agente (playground) no salen en la lista ni en `total`.
- `total` cuenta todas las conversaciones que cumplen el filtro, no las de la página. Cuando `totalIsCapped` es `true`, el número real es mayor.
- Con `from`/`to` (fechas `AAAA-MM-DD` en la zona del espacio de trabajo) acotas un periodo; la respuesta lo confirma en `period`.

## Página: `page` + `limit`

`resources/list` numera las páginas desde 1 y devuelve un objeto `pagination` con `page`, `limit`, `total` y `totalPages`. Sigue mientras `page < totalPages`.

## Una sola página

`templates/search`, `analytics/lead-attribution` y `voice/calls` aceptan `limit` pero no tienen siguiente página: devuelven lo más reciente o lo más relevante hasta ese límite. Para ver más, sube `limit` hasta su máximo o acota con los filtros de la ruta.

## Límites

- Un `limit` fuera de rango (`0`, o más que el máximo de la tabla) responde `400`. Pide el máximo, no más.
- Cada página es una solicitud y cuenta contra tu [límite de 60 por minuto](/guides/authentication#límites-de-tasa). En exportaciones largas, lee `X-RateLimit-Remaining` y espera a `X-RateLimit-Reset` cuando llegue a cero.
