> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Paginación

> Obtén conjuntos completos de resultados desde los endpoints de lista de YCloud.

## Qué es

La paginación te permite recuperar colecciones grandes en respuestas delimitadas. Los
endpoints de lista de YCloud utilizan paginación por número de página o por cursor.

## Antes de comenzar

Consulta la referencia del endpoint para conocer los parámetros de paginación, filtros,
orden de clasificación y estructura de respuesta admitidos. No asumas que todos los endpoints de lista utilizan la misma
estrategia.

## Cómo funciona

Solicita una página, procesa sus elementos y continúa hasta que la respuesta indique
que no existe una página siguiente. Mantén los mismos filtros y ajustes de ordenación durante
todo el recorrido.

## Solicitud y respuesta

### Paginación por número de página

La mayoría de los endpoints de lista admiten estos parámetros de consulta:

| Parámetro | Descripción |
| - | - |
| `page` | Número de página. Comienza en `1` y su valor predeterminado es `1`. |
| `limit` | Resultados por página. Va de `1` a `100` y su valor predeterminado es `10`. |
| `includeTotal` | Establécelo en `true` para incluir el número total de elementos coincidentes. |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.ycloud.com/v2/contact/contacts?page=1&limit=100&includeTotal=true" \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

La respuesta de una página contiene:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "offset": 0,
  "limit": 100,
  "length": 2,
  "total": 2,
  "items": [{ "id": "ITEM_1" }, { "id": "ITEM_2" }]
}
```

| Campo de respuesta | Significado |
| - | - |
| `items` | Objetos devueltos en esta página. |
| `offset` | Posición inicial basada en cero: `(page - 1) * limit`. |
| `limit` | Tamaño de página solicitado. |
| `length` | Número real de elementos, igual a `items.length` y no mayor que `limit`. |
| `total` | Total de elementos coincidentes; se devuelve solo cuando `includeTotal=true`. Realizar el recuento puede añadir latencia, por lo que debes solicitarlo solo cuando sea necesario. |

<Note>
  Los endpoints basados en desplazamiento suelen limitar tanto `page` como `limit` a 100, lo que limita
  el recorrido a los primeros 10 000 elementos. Comprueba los límites de cada endpoint y utiliza
  la paginación por cursor cuando sea compatible y necesites un conjunto de resultados mayor.
</Note>

Continúa solicitando la siguiente página mientras `length` sea igual a `limit`. Deténte cuando `length` sea menor que `limit`.

### Paginación por cursor

Los endpoints que devuelven `cursor.after` admiten paginación por cursor. Envía ese valor como `pageAfter` en la siguiente solicitud.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.ycloud.com/v2/unsubscribers?limit=100&pageAfter=id%3Afoo" \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

Una respuesta por cursor contiene `items`, `limit`, `length` y, cuando existen más
resultados, `cursor.after`. El objeto de cursor solo lo devuelven los endpoints que
admiten paginación por cursor.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [{ "id": "ITEM_1" }],
  "limit": 1,
  "length": 1,
  "cursor": { "after": "id:foo" }
}
```

Pasa el cursor devuelto sin cambios a la siguiente solicitud. Trátalo como opaco;
no lo modifiques ni lo almacenes como un identificador de aplicación a largo plazo. Deténte cuando
`length` sea `0` o la respuesta ya no contenga `cursor.after`.

<Note>
  Los parámetros de paginación y filtro varían según el endpoint. Consulta la referencia de la API antes de implementar una operación de lista.
</Note>

## Lista de verificación para la implementación

* Define un `limit` explícito en lugar de depender del valor predeterminado.
* Mantén los filtros entre solicitudes de página.
* Deténte en función de la condición de la respuesta, no de un recuento de páginas estimado.
* Maneja una primera página vacía como un resultado exitoso.
* Añade un límite de seguridad de páginas o elementos máximos para tareas en segundo plano.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.