> ## 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.

# Paginação

> Obtenha conjuntos completos de resultados a partir de endpoints de listagem da YCloud.

## O que é

A paginação permite recuperar grandes coleções em respostas delimitadas. Os endpoints
de listagem da YCloud usam paginação por número de página ou por cursor.

## Antes de começar

Consulte a referência do endpoint para verificar os parâmetros de paginação compatíveis, filtros,
ordem de classificação e o formato da resposta. Não presuma que todos os endpoints de listagem utilizam a mesma
estratégia.

## Como funciona

Solicite uma página, processe seus itens e continue até que a resposta indique
que não há uma próxima página. Mantenha os mesmos filtros e configurações de classificação durante toda a
varredura.

## Requisição e resposta

### Paginação por número de página

A maioria dos endpoints de listagem aceita estes parâmetros de consulta:

| Parâmetro | Descrição |
| - | - |
| `page` | Número da página. Começa em `1` e tem como padrão `1`. |
| `limit` | Resultados por página. Varia de `1` a `100` e tem como padrão `10`. |
| `includeTotal` | Defina como `true` para incluir o número total de itens correspondentes. |

```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"
```

A resposta de uma página contém:

```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 resposta | Significado |
| - | - |
| `items` | Objetos retornados nesta página. |
| `offset` | Posição inicial baseada em zero: `(page - 1) * limit`. |
| `limit` | Tamanho de página solicitado. |
| `length` | Número real de itens, igual a `items.length` e não superior a `limit`. |
| `total` | Total de itens correspondentes; retornado apenas quando `includeTotal=true`. Fazer a contagem pode adicionar latência, portanto solicite apenas quando necessário. |

<Note>
  Endpoints baseados em deslocamento (offset) normalmente limitam tanto `page` quanto `limit` em 100, limitando
  a varredura aos primeiros 10.000 itens. Verifique os limites de cada endpoint e use
  paginação por cursor quando houver suporte e você precisar de um conjunto maior de resultados.
</Note>

Continue solicitando a próxima página enquanto `length` for igual a `limit`. Pare quando `length` for menor que `limit`.

### Paginação por cursor

Endpoints que retornam `cursor.after` têm suporte a paginação por cursor. Passe esse valor como `pageAfter` na próxima requisição.

```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"
```

Uma resposta de cursor contém `items`, `limit`, `length` e, quando existirem mais resultados,
`cursor.after`. O objeto de cursor é retornado apenas por endpoints compatíveis com
paginação por cursor.

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

Envie o cursor retornado sem alterações para a próxima requisição. Trate-o como opaco;
não o modifique nem o armazene como um identificador de longo prazo da aplicação. Pare quando
`length` for `0` ou se a resposta não contiver mais `cursor.after`.

<Note>
  Os parâmetros de paginação e filtro variam conforme o endpoint. Consulte a referência da API antes de implementar uma operação de listagem.
</Note>

## Checklist de implementação

* Defina um `limit` explícito em vez de depender do padrão.
* Mantenha os filtros entre as requisições de página.
* Interrompa com base na condição da resposta, e não em uma estimativa da contagem de páginas.
* Trate uma primeira página vazia como um resultado bem-sucedido.
* Adicione um limite de segurança de páginas ou itens máximos para tarefas em segundo plano.


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