Paginação de API no n8n: buscando todos os registros sem perder nenhum
Os dois modos de paginação do HTTP Request com as expressões exatas, por que $pageCount começa em zero e como não criar um laço infinito.
Resumo por IA
Resumo gerado por IA, revisado pela redação.
Quase toda API devolve resultados em páginas, e um fluxo que ignora isso traz só os primeiros registros — sem erro nenhum, o que é pior. O n8n resolve isso dentro do próprio node HTTP Request: em Add Option → Pagination você escolhe entre seguir a URL que a resposta indica ou incrementar um número de página a cada volta. São duas configurações curtas, e este texto mostra as duas com a expressão exata.
Adicione ao Google NotíciasAntes de configurar: três perguntas
APIs implementam paginação de formas diferentes, e a documentação da API é quem responde. Antes de mexer no node, descubra:
A API fornece a URL da próxima página na resposta? Se sim, o primeiro modo é o mais simples.
Existem limites de tamanho ou de número de página? Muitas travam em 100 registros por vez.
Qual é a estrutura da resposta? Você vai precisar apontar o caminho exato do campo.
Modo 1: a resposta traz a próxima URL
É o formato mais confortável. A API devolve, junto com os dados, o endereço da página seguinte.
A configuração:
Defina o modo de paginação como Response Contains Next URL.
No campo da próxima URL, use uma expressão apontando para o campo que traz esse endereço.
A expressão exata depende do nome que a API usa. Se o campo se chama next-page e vem no corpo da resposta:
{{ $response.body["next-page"] }}A variável $response dá acesso à resposta da requisição anterior — é isso que permite encadear.
Repare no uso de colchetes com aspas: o nome tem hífen, e a notação de ponto não funciona nesse caso. Se o campo da sua API tiver nome simples, {{ $response.body.next }} resolve.
Modo 2: incrementar o número da página
Quando a API não devolve a próxima URL mas aceita um parâmetro de página, o caminho é outro:
Defina o modo como Update a Parameter in Each Request.
Defina o tipo como Query.
Informe o nome do parâmetro — normalmente
page, mas confira na documentação.Ative expressão no campo de valor e escreva:
{{ $pageCount + 1 }}Por que o + 1? Porque $pageCount conta quantas páginas o node já buscou e começa em zero, enquanto a maioria das APIs numera a partir de um. Com o incremento, a primeira volta busca a página 1, a segunda busca a 2, e assim por diante.
Onde parar
Essa é a parte que exige atenção, porque um fluxo que não sabe parar vira um problema.
Nos dois modos existe uma condição de parada. No primeiro, ela é natural: quando a resposta não traz mais a próxima URL, acabou. No segundo, você precisa dizer quando parar — normalmente quando a resposta vier vazia ou quando o número de páginas atingir um teto.
Sempre defina um teto máximo de páginas, mesmo quando tiver certeza da condição de parada. Um erro na condição, somado a uma API que devolve a mesma página para sempre, produz um laço infinito que consome execuções e pode fazer o serviço bloquear o seu acesso. Um teto de segurança custa nada.
O efeito sobre o resto do fluxo
Duas consequências práticas que pegam desprevenido:
O volume muda de ordem de grandeza. Um fluxo que trazia 100 registros passa a trazer 4.000. Se o node seguinte envia mensagem, você acabou de multiplicar por quarenta o que ele faz. Confira a contagem de itens antes de ativar.
O tempo cresce. Cada página é uma requisição. Quarenta páginas com meio segundo cada são vinte segundos só de busca. Em fluxo com limite de tempo, isso importa.
Quando não paginar
Vale considerar a alternativa: em vez de trazer tudo e filtrar depois, filtre na origem. Se a API aceita parâmetros de busca — por data, por status —, pedir só o que interessa costuma ser mais rápido, mais barato e menos sujeito a limite de uso do que paginar o acervo inteiro.
A regra prática: pagine quando precisar mesmo de todos os registros; filtre quando precisar de um subconjunto.
Duas configurações resolvem quase tudo: seguir a URL da resposta com $response, ou incrementar a página com {{ $pageCount + 1 }}. E sempre um teto de páginas por segurança.
Perguntas frequentes
Como configurar paginação no n8n?
No node HTTP Request, em Add Option, escolhendo Pagination. A partir daí existem dois modos: seguir a URL da próxima página que vem na resposta, ou atualizar um parâmetro de página a cada requisição.
O que é $pageCount no n8n?
É a variável que indica quantas páginas o node HTTP Request já buscou. Ela começa em zero, e como a maioria das APIs numera a partir de um, a expressão usada é {{ $pageCount + 1 }} — assim a primeira volta pede a página 1.
Como pegar a próxima página quando a API devolve a URL?
Definindo o modo de paginação como "Response Contains Next URL" e apontando, por expressão, o campo da resposta que traz esse endereço — por exemplo {{ $response.body["next-page"] }}, ajustando o nome do campo conforme a API.
Por que meu fluxo só traz os primeiros registros?
Porque a paginação não está configurada e a API devolveu apenas a primeira página. Não há mensagem de erro nesse caso: o fluxo funciona normalmente com dados incompletos, o que torna o problema difícil de perceber.
Como evitar um laço infinito na paginação?
Definindo sempre um número máximo de páginas, além da condição de parada. Se a condição falhar e a API continuar devolvendo conteúdo, o teto interrompe o processo antes que ele consuma execuções e provoque bloqueio por excesso de requisições.
Este tutorial faz parte do guia Curso de n8n do zero ao avançado: o guia completo em português. Veja também: Node, trigger e workflow: o vocabulário do n8n em 10 minutos · A estrutura de dados do n8n: por que tudo é um array com json · Item linking no n8n: como ele decide qual item vai pra saída · Execuções passo a passo: como achar onde o fluxo do n8n quebrou · A Canvas UI do n8n 2.0: o que mudou e como se orientar · n8n Cloud ou self-hosted: a decisão que define seu custo e sua liberdade
