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

# Paginação

> Todos os endpoints de listagem usam o mesmo padrão page/limit. A resposta inclui contagens totais para você construir UIs paginadas.

Endpoints de listagem (`GET /agents`, `GET /conversations`, `GET /clients`, etc.) usam um único shape consistente: **page + limit**.

## Requisição

```bash theme={null}
curl "https://api.gennia.ai/public/api/v1/agents?page=2&limit=50" \
  -H "X-Api-Key: $GENNIA_API_KEY"
```

| Parâmetro | Tipo        | Default | Máx   |
| --------- | ----------- | ------- | ----- |
| `page`    | integer ≥ 1 | `1`     | —     |
| `limit`   | integer     | `20`    | `100` |

Paginação inválida (page \< 1, limit > 100) retorna `400 VALIDATION_ERROR`.

## Envelope da resposta

Toda resposta paginada envolve os items no mesmo shape:

```json theme={null}
{
  "items": [
    { "publicId": "...", "name": "..." },
    ...
  ],
  "page": 2,
  "limit": 50,
  "total": 123,
  "totalPages": 3
}
```

| Campo        | Significado                                       |
| ------------ | ------------------------------------------------- |
| `items`      | Os resultados da página.                          |
| `page`       | Echo da página requisitada (1-indexed).           |
| `limit`      | Echo do limit requisitado.                        |
| `total`      | Contagem total de resultados em todas as páginas. |
| `totalPages` | `ceil(total / limit)`.                            |

## Iterando por todas as páginas

```bash theme={null}
page=1
while :; do
  resp=$(curl -s "https://api.gennia.ai/public/api/v1/agents?page=$page&limit=100" \
    -H "X-Api-Key: $GENNIA_API_KEY")
  echo "$resp" | jq -c '.items[]'
  total_pages=$(echo "$resp" | jq -r '.totalPages')
  [ "$page" -ge "$total_pages" ] && break
  page=$((page + 1))
done
```

<Tip>
  Quando você não souber o total antes, dá pra parar assim que `items` voltar vazio. Mas sempre confira `totalPages` se precisar de comportamento consistente de fim-de-dados.
</Tip>

## Filtros

A maioria dos endpoints de listagem aceita query parameters adicionais pra restringir resultado:

| Endpoint                 | Filtros típicos               |
| ------------------------ | ----------------------------- |
| `GET /agents`            | `includeArchived`             |
| `GET /clients`           | `status`, `q` (busca textual) |
| `GET /conversations`     | `status`, `agentPublicId`     |
| `GET /knowledge-sources` | `status`, `search`            |

Veja a página de cada endpoint na referência para a lista completa.

## Ordenação estável

Resultados são **ordenados por `createdAt` descendente** (mais novos primeiro), exceto onde a documentação do endpoint especifique o contrário. Isso significa que recursos novos podem aparecer na primeira página durante iteração — se precisar de um snapshot estável, capture uma vez e guarde os IDs.