# Paginación basada en cursor — Guía de next_page_token

> Los endpoints de lista en la API v1 utilizan paginación basada en cursor opaco — no números de página — mediante un next_page_token que usted devuelve textualmente, sin decodificar ni construir por su cuenta.

Cada endpoint de lista en v1 (`GET /batches`, `GET /account/usage` y cualquier otro endpoint de lista futuro) se pagina de la misma forma: un cursor, no un número de página.

## El envolvente de lista

Toda respuesta de lista tiene los mismos tres campos de nivel superior:

```json
{
  "data": [ /* ... */ ],
  "has_more": true,
  "next_page_token": "eyJpZCI6IDQyfQ"
}
```

- `data` — el arreglo de resultados de esta página.
- `has_more` — indica si existe otra página después de esta.
- `next_page_token` — devuélvalo como `?page_token=` en su próxima solicitud para obtener la página siguiente. Siempre es `null` cuando `has_more` es `false`; ambos campos nunca discrepan.

## Por qué un cursor, no un número de página

No existe paginación estilo `?page=2` en ninguna parte de v1, ni un parámetro `offset`. Listas como sus lotes o su historial de uso cambian constantemente — se completan nuevos lotes, se escriben nuevas filas de uso — por lo que una "página 2" basada en desplazamiento puede omitir o repetir filas silenciosamente si algo se inserta entre sus solicitudes. Un cursor evita eso: cada token apunta a una posición exacta en el orden subyacente, no a un desplazamiento numérico cambiante.

## El token es opaco

`next_page_token` no es un número de página, y su codificación interna no forma parte del contrato — trátelo estrictamente como una cadena opaca. Devuélvalo exactamente como lo recibió; no lo decodifique, no construya el suyo propio y no asuma que su formato es estable entre versiones de la API. La única garantía es: pase el token que se le entregó, obtenga la página siguiente.

## Ejemplo: paginación a través de sus lotes

Primera solicitud, aún sin token:

```bash
curl "https://imagetotable.ai/api/v1/batches?limit=20" \
  -H "Authorization: Bearer $API_KEY"
```

```json
{
  "data": [ { "batch_name": "260716-4K9P", "status": "succeeded", "document_count": 3, "created_at": "2026-07-16T09:12:03Z" } ],
  "has_more": true,
  "next_page_token": "eyJpZCI6IDQyfQ"
}
```

Siguiente solicitud, usando el token de la respuesta anterior:

```bash
curl "https://imagetotable.ai/api/v1/batches?limit=20&page_token=eyJpZCI6IDQyfQ" \
  -H "Authorization: Bearer $API_KEY"
```

Siga repitiendo con el `next_page_token` de cada respuesta hasta que `has_more` devuelva `false`. Un token mal formado o expirado devuelve un error `invalid_parameter` (consulte [Manejo de errores](/developers/guides/errors)) en lugar de devolver silenciosamente la primera página nuevamente — así que un token corrupto se manifiesta de inmediato en lugar de reiniciar su bucle sin aviso.

## El parámetro `limit`

Cada endpoint de lista acepta un parámetro de consulta `limit` opcional para controlar el tamaño de página, cada uno con su propio valor predeterminado y máximo (consulte la página del endpoint individual en [Referencia de la API](/developers/reference/) para conocer sus límites exactos). Solicitar un `limit` fuera del rango permitido devuelve `invalid_parameter`.

---

Source: https://imagetotable.ai/es/developers/guides/pagination