Pagination API dans n8n : boucler proprement sur les grandes listes de données

Un besoin revient dans presque tous les workflows qui consomment une API externe : récupérer toute une liste — les contacts d'un CRM, les commandes d'une boutique, les tickets d'un support — alors que l'API ne renvoie jamais plus de 20, 50 ou 100 résultats par appel. La tentation est de tester avec la première page, que ça fonctionne, puis de découvrir en production que seuls les 50 premiers contacts ont été synchronisés. Ce guide détaille comment gérer proprement la pagination dans n8n, de l'option native du node HTTP Request à la boucle manuelle pour les cas particuliers.

Les trois façons dont une API pagine ses résultats

Avant de configurer quoi que ce soit, il faut identifier le mécanisme exposé par l'API cible — il conditionne toute la suite :

• Pagination par numéro de page ou offset (?page=2 ou ?offset=50&limit=50) : la plus simple, mais fragile si les données changent entre deux appels (un élément inséré en cours de route décale toute la suite).
• Pagination par curseur ou jeton (?cursor=eyJpZCI6MTIzfQ ou un champ next_token dans la réponse) : plus robuste face aux insertions concurrentes, utilisée par Stripe, HubSpot ou l'API Notion.
• Pagination par URL complète (un champ next ou un header Link qui contient déjà l'URL entière de la page suivante, comme sur GitHub) : la plus simple à suivre, puisqu'il n'y a rien à reconstruire soi-même.

Le type de pagination détermine directement le réglage à choisir dans le node HTTP Request.

La méthode native : l'option Pagination du node HTTP Request

Dans le node HTTP Request, l'onglet Options propose une entrée Pagination qui couvre la majorité des cas sans écrire une seule ligne de logique de boucle :

• Update a Parameter in Each Request : n8n incrémente automatiquement un paramètre (page, offset) à chaque appel. L'expression {{ $pageCount + 1 }} référence le numéro d'itération courant — pratique pour des API qui paginent à partir de 1 alors que $pageCount démarre à 0.
• Response Contains Next URL : n8n suit directement l'URL de page suivante renvoyée dans la réponse (champ JSON ou header Link), sans avoir à reconstruire l'URL vous-même.

Dans les deux cas, une condition d'arrêt est obligatoire (nombre de pages maximum, ou expression du type « le tableau items de la réponse est vide ») : sans elle, le node continue d'interroger l'API indéfiniment, ce qui finit en erreur de rate limit ou en exécution qui ne se termine jamais.

Ce réglage suffit pour la grande majorité des intégrations REST classiques, et c'est la première option à essayer avant de complexifier un workflow — dans le même esprit que le choix entre Split In Batches et boucle simple : commencer par l'outil natif avant de bricoler une solution maison.

Quand la pagination native ne suffit pas : la boucle manuelle

Certaines API ne rentrent pas dans ces deux cases : jeton d'authentification à courte durée de vie à rafraîchir entre deux pages, pause dynamique à respecter selon un header X-RateLimit-Remaining, ou besoin de traiter (écrire en base, notifier) chaque page au fur et à mesure plutôt qu'attendre la fin de la récupération complète. Dans ces cas, le schéma classique combine trois nodes :

1. Un node HTTP Request qui récupère une page.
2. Un node IF qui teste la condition d'arrêt (curseur vide, page au-delà du total annoncé par l'API, tableau de résultats vide).
3. Un node Loop Over Items (anciennement Split In Batches) ou un rebouclage du node HTTP Request lui-même, tant que la condition d'arrêt n'est pas remplie.

L'avantage de cette approche par rapport à la pagination native : chaque page peut être traitée immédiatement (insertion Supabase, vérification de doublon, notification) au lieu d'accumuler tous les résultats en mémoire jusqu'à la fin. C'est le réglage à privilégier dès que le volume dépasse quelques centaines d'éléments, pour éviter qu'une exécution géante échoue au bout de vingt minutes sans avoir rien persisté.

Exemple concret : synchroniser tous les contacts d'un CRM

Dans un workflow proche de ceux du Pack Assistant RAG (119 €) pour la synchronisation Notion, ou d'une synchronisation CRM HubSpot/Pipedrive, la boucle typique ressemble à : appeler l'endpoint /contacts avec le curseur courant, insérer chaque contact reçu dans une table Supabase (avec un upsert sur l'identifiant externe pour éviter les doublons), puis relancer l'appel avec le next_cursor renvoyé par l'API — jusqu'à ce que ce champ soit vide. Le même schéma s'applique à la récupération de commandes dans un workflow e-commerce ou de tickets support pour un scoring par IA.

Pièges courants

• Rate limiting : une pagination trop agressive (pas de délai entre les appels) déclenche vite des erreurs 429 sur les API à quota serré. Voir notre guide sur la gestion des erreurs 429 pour les stratégies de backoff à combiner avec une boucle de pagination.
• Mémoire de l'exécution : accumuler des dizaines de milliers d'items dans un seul tableau avant de les traiter en bloc peut ralentir fortement l'exécution, voire la faire échouer sur une instance aux ressources limitées. Écrire au fil de l'eau (page par page) plutôt qu'à la fin règle le problème dans la quasi-totalité des cas.
• Doublons après une reprise : si le workflow échoue à la page 40 sur 100 et repart de zéro au prochain déclenchement, les 39 premières pages sont retraitées. Un Error Workflow combiné à une table de suivi (dernier curseur traité, stockée par exemple dans une Data Table n8n ou Supabase) permet de reprendre exactement là où l'exécution s'est arrêtée plutôt que de tout recommencer.
• Condition d'arrêt mal définie : tester items.length > 0 fonctionne pour la plupart des API, mais certaines renvoient un tableau vide avant la dernière page réelle, ou au contraire continuent de renvoyer un curseur non nul après la fin logique des données. Toujours vérifier le comportement réel de l'API en fin de pagination plutôt que de se fier uniquement à sa documentation.

Pourquoi automatiser plutôt que paginer « à la main »

Avant d'automatiser cette étape, l'alternative reste de cliquer manuellement sur « page suivante » dans une interface web puis de copier les données dans un tableur — une pratique encore fréquente pour de petits volumes ponctuels. Une étude de Barchard et Pace (Preventing human error: The impact of data entry methods on data accuracy and statistical results, Computers in Human Behavior, 2011 — voir sur Google Scholar) montre que la simple vérification visuelle de données saisies manuellement génère 29 à 58 % d'erreurs en plus qu'une double saisie contrôlée, et que ces erreurs modifient parfois significativement les résultats en aval. Une boucle de pagination correctement bornée et testée élimine cette classe d'erreurs par construction : chaque page est traitée de façon identique, sans fatigue ni oubli, du premier au dernier appel.

Pour aller plus loin

La pagination est une brique presque invisible une fois bien réglée, mais elle conditionne la fiabilité de tout workflow qui dépend d'une liste complète plutôt que d'un simple aperçu. Commencer par l'option Pagination native du node HTTP Request, ne passer à une boucle manuelle avec Loop Over Items que si le cas d'usage l'exige vraiment, et toujours traiter les pages au fil de l'eau plutôt qu'en bloc : ces trois réflexes évitent l'essentiel des mauvaises surprises. Les workflows des packs FlowKit appliquent systématiquement ce principe partout où une API externe est interrogée en volume — du Pack Inbox IA (79 €) au Pack Conformité & Audit (149 €).