BLOG
Paginação de API no n8n evita que uma resposta limitada deixe registros para trás, mas o workflow precisa pedir todas as páginas e reconhecer quando parar. No n8n, o HTTP Request node oferece modos de paginação configuráveis; a regra depende de como a API informa página, offset, cursor ou URL seguinte. Para a API pública do próprio n8n, a documentação usa `nextCursor`. Esses mecanismos não são intercambiáveis: leia a resposta real e siga o formato do serviço.
Se uma página falha por limite de requisições, veja também nosso guia de Retry On Fail, Wait e Batching para erros 429 no n8n; retentativa não substitui a conferência de paginação.
Nota editorial: análise baseada nas fontes oficiais vinculadas e no Planejador Google; não houve teste próprio. Preços, acesso, limites e funcionalidades podem mudar e devem ser confirmados no serviço antes da implantação.
Paginação de API no n8n: descubra o formato
Faça uma chamada de leitura pequena e examine o corpo, cabeçalhos e parâmetros aceitos. Uma API pode devolver `next`, `nextCursor`, `page`, `offset`, `has_more` ou simplesmente um array sem metadados. Confirme se a página começa em 0 ou 1, qual tamanho máximo e se o cursor expira. Não use um campo imaginado porque outro provedor o utiliza. A documentação da API e um exemplo de resposta de teste são a base para configurar a paginação.
No HTTP Request do n8n, configure a paginação para alterar o query parameter, body, header ou URL conforme esse contrato. Se a API retorna uma URL absoluta seguinte, valide o domínio antes de permitir que o node a siga; isso evita chamadas acidentais a hosts inesperados. Para cursor, capture exatamente o valor retornado. Para offset, incremente pelo tamanho real recebido, não necessariamente pelo máximo solicitado.
Referência: n8n HTTP Request pagination.
Defina uma condição de parada explícita
Com cursor, continue enquanto existir um cursor válido e pare quando o campo não vier ou for nulo. Com paginação por número, pare quando a API indicar `has_more=false` ou quando uma página vier vazia, desde que a documentação garanta esse comportamento. Um limite máximo de páginas é uma proteção contra loop infinito, não substitui o critério de término. Registre quando o limite de segurança foi alcançado e não apresente o lote como completo.
Se o n8n oferece `$pageCount` para compor parâmetros, verifique a indexação esperada na documentação da versão. Um erro de uma unidade pode repetir a primeira página ou pular registros. Teste com uma fonte contendo mais que uma página e compare IDs. Para API que pode mudar durante coleta, use ordenação estável ou janela de data; novos registros inseridos no início podem deslocar offsets e causar lacunas.
Referência: n8n API pagination.
Como evitar duplicação quando o workflow repete
Uma execução pode falhar depois de processar páginas iniciais ou após o serviço aceitar uma escrita e a resposta se perder. Ao reiniciar, o workflow pode reenviar os mesmos registros. Use um identificador único e faça upsert ou consulta de existência. Se o destino suporta chave de idempotência, envie a mesma chave para a mesma entidade em todas as tentativas. Não gere um ID novo a cada repetição.
Para coletar em intervalos, guarde o checkpoint da última posição ou data confirmada apenas depois de persistir os resultados. Se houver falha, retome do checkpoint anterior com sobreposição pequena e elimine duplicatas por ID. A janela de sobreposição protege contra atrasos e ordenação instável, mas exige deduplicação. Nunca atualize o checkpoint antes de salvar todos os itens da página; isso transforma falha parcial em perda permanente.
Referência: n8n API reference.
Respeite limite de taxa e tamanho de resposta
A API pode retornar 429, `Retry-After` ou limites próprios. Configure intervalos e backoff quando apropriado, com número máximo de tentativas. Não dispare dezenas de requisições paralelas sem confirmar quota e estabilidade; paralelismo pode acelerar e também aumentar bloqueios ou inconsistências. Reduza campos retornados, filtre no servidor e use lotes do tamanho aceito. Evite colocar toda a resposta em memória se houver grande volume.
A resposta pode variar em bytes mesmo com tamanho fixo de registros. Considere timeouts, limite de payload e armazenamento incremental. Se o provedor cobra por chamada, estime páginas por execução e frequência. Uma rotina diária com centenas de páginas tem custo operacional diferente de uma consulta manual. Mantenha alerta para loop e crie um botão de stop operacional se a coleta ficar presa.
Referência: n8n HTTP Request pagination.
Valide completude, não apenas status 200
HTTP 200 diz que houve resposta, não que todos os itens foram recuperados. Compare IDs únicos coletados, número informado pelo provedor, quantidade persistida e páginas percorridas. Verifique duplicatas, lacunas de sequência, registros sem campos obrigatórios e contagem após filtro. Se o destino recebeu parte do lote e o workflow falhou, marque execução parcial e permita reconciliação.
Crie um conjunto de teste conhecido com exatamente mais de uma página e um último registro que deve aparecer na página final. Teste página vazia, cursor ausente, cursor repetido, erro 429 e timeout. Se um cursor se repete, interrompa e gere alerta em vez de repetir indefinidamente. Salve dados de execução necessários à investigação, minimizando conteúdo pessoal e segredos.
Referência: n8n API pagination.
Paginação da API pública do n8n
A documentação da API do n8n descreve paginação por cursor `nextCursor`; use a operação específica e siga o cursor na próxima solicitação até o término. A documentação também informa limites e parâmetros da API. Não aplique automaticamente a configuração do HTTP Request genérico: aquele node pagina conforme o contrato da API externa, enquanto endpoints do n8n API têm seu próprio esquema.
Se usar a API para inventariar workflows, gere primeiro um relatório somente de leitura. Registre total, páginas, erros e horário da coleta. Se a lista mudar durante a consulta, uma segunda passagem pode ser necessária para reconciliar. Não conclua que uma instância tem poucos workflows só porque a primeira resposta retornou poucos itens. Controle a chave API como segredo de alto impacto e não a exponha em workflow público.
Referência: n8n API reference.
Estratégia de retomada para grandes volumes
Divida grandes extrações por janela temporal, conta ou recurso, e persista cada página com checkpoint. Armazene a assinatura da execução e a página atual; se o processo reiniciar, retome com idempotência. Para mudanças incrementais, prefira `updated_at` ou cursor de alteração quando a API oferecer. Faça reconciliação periódica completa para capturar itens alterados fora da janela.
Mantenha versão do esquema e transforme os campos em uma camada previsível antes de gravar. Mudanças de API podem adicionar campos ou mudar estrutura; não descarte dados silenciosamente. Avise quando respostas divergem do esquema esperado. Se o volume cresce, avalie fila ou banco em vez de carregar tudo em uma única execução n8n. Teste recuperação após reiniciar o workflow e compare com uma exportação de referência.
Referência: n8n HTTP Request pagination.
Checklist para colocar em produção
Documente endpoint, tipo de paginação, tamanho, cursor, condição de parada, limite de segurança, taxa, tratamento de 429, ID de deduplicação, checkpoint e métrica de completude. Rode teste com duas ou mais páginas e force uma falha no meio. Confirme que a retomada não duplica e que a execução parcial não é marcada como completa.
Depois do lançamento, acompanhe páginas médias, tempo, falhas, volume de duplicatas e registros reconciliados. Mudanças no provedor ou no node podem alterar comportamento. Revise o fluxo quando endpoint, credencial ou versão for atualizada. Uma implementação correta é específica à API consultada; sem documentação e exemplo de resposta, não há fórmula universal que garanta coleta completa.
Referência: n8n API pagination.
Perguntas frequentes
Como sei que a API terminou?
Use o campo de término documentado, como ausência de nextCursor ou `has_more=false`; limite de páginas é apenas proteção.
Cursor e offset são iguais?
Não. Cursor aponta uma posição opaca retornada pela API; offset costuma indicar um deslocamento numérico.
O HTTP 200 prova que baixei tudo?
Não. Valide contagem, páginas, IDs únicos e persistência contra uma referência.
Como evitar duplicatas após falha?
Use chave única, upsert ou idempotência e atualize checkpoint apenas após persistir a página.
A paginação da n8n API é a mesma do HTTP Request?
Não necessariamente. A API pública do n8n documenta nextCursor; o HTTP Request segue o contrato da API chamada.
Fontes principais: n8n HTTP Request pagination; n8n API pagination; n8n API reference.
