## Visão geral

Uma ferramenta HTTP personalizada deixa o Robô chamar a sua API. Quando essa API devolve listas, ela
quase sempre devolve em **páginas** — e sem configurar isso o Robô lê só a primeira e responde com
uma parte dos dados sem saber que faltou o resto.

A **Paginação** resolve isso. Você diz de que tipo ela é, onde estão os itens na resposta e até
quantas páginas percorrer. E, opcionalmente, **quantos itens pedir por página**.

## Pré-requisitos

- Um Robô com pelo menos uma ferramenta HTTP personalizada configurada.
- Saber como a sua API pagina: por número de página ou por cursor.
- Acesso de administrador da conta.

## Passo a passo

1. Abra **Configurações → Robôs** e edite o Robô.
2. Vá até **Ferramentas personalizadas** e abra a ferramenta.
3. Em **Paginação**, escolha o tipo: **Sem paginação**, **Número de página** ou **Cursor**.
4. Preencha os campos da paginação (veja a tabela abaixo).
5. Salve.

## Configurações & opções

| Campo | Para que serve |
|---|---|
| Tipo | **Sem paginação**, **Número de página** ou **Cursor** |
| Param de página/cursor | O nome do parâmetro que a API usa para avançar (`page`, `cursor`…) |
| Caminho dos itens (array) | Onde, na resposta, está a lista de resultados |
| Caminho do próximo cursor | Onde vem o cursor da próxima página (só no tipo cursor) |
| Página inicial | Por qual página começar |
| Máx. páginas | Teto de páginas a percorrer numa chamada |
| **Param do tamanho da página** | O nome do parâmetro de tamanho da sua API (`per_page`, `limit`…) |
| **Itens por página** | O valor enviado nesse parâmetro |

Os dois últimos são **opcionais e andam juntos**: deixar em branco significa não enviar o parâmetro,
e aí a API decide o tamanho.

## Casos de uso

- **API cujo padrão é 100 itens por página**: defina `per_page` = 20. Cada página vira um pedaço que
  cabe confortavelmente no contexto, e **Máx. páginas** controla até onde ir.
- **API que devolve tudo de uma vez**: se ela aceitar um parâmetro de limite, use-o. Uma resposta
  enorme numa tacada consome o contexto do modelo e sobra pouco para o raciocínio e para a resposta.
- **API com cursor**: preencha **Caminho do próximo cursor**; o tamanho da página continua valendo.

## Dicas, limites e boas práticas

- Comece com um valor modesto (10 a 25) e suba só se as respostas ficarem incompletas.
- Tamanho de página menor com **Máx. páginas** maior costuma ser melhor que uma página gigante:
  o Robô consegue parar quando já achou o que precisava.
- O parâmetro tem que existir na sua API. Um nome que ela não conhece costuma ser ignorado em
  silêncio — e você fica com a impressão de que a configuração não fez efeito.
- Deixar em branco é uma escolha válida quando o padrão da API já é razoável.

## Solução de problemas

**O Robô responde com dados parciais.** Ou a paginação está em **Sem paginação**, ou **Máx. páginas**
está baixo demais para o volume que a consulta devolve.

**A ferramenta demora muito.** Cada página é uma chamada HTTP. Reduza **Máx. páginas** ou aumente os
itens por página para buscar o mesmo volume em menos idas e vindas.

**Mudei os itens por página e nada mudou.** Confirme o nome do parâmetro com a documentação da sua
API — `per_page`, `limit`, `page_size` e `pageSize` são todos comuns, e só um deles é o certo.

**A lista chega vazia.** O **Caminho dos itens** não está apontando para o array certo na resposta.

## Veja também

- [Ajustes avançados do modelo](/hc/ajuda/articles/maestro-brain-ajustes-avancados-do-modelo-pt-br)
- [Ferramentas do Maestro por módulo](/hc/ajuda/articles/maestro-brain-ferramentas-maestro-por-modulo-pt-br)