Oncrawl Data Reader

Le node Oncrawl Data Reader interroge les pages, liens, clusters ou données structurées d'un crawl Oncrawl terminé, avec un filtre OQL validé contre le schéma du crawl.

Que fait le node Oncrawl Data Reader ?#

Le node Oncrawl Data Reader interroge les données collectées par un crawl Oncrawl, via l’API Data officielle. Quatre types de données sont disponibles — pages, liens, clusters de duplication et données structurées — et le filtre s’écrit en OQL, le langage de requête d’Oncrawl.

Là où le node Oncrawl KPI Reader répond à « combien de pages ont été crawlées », celui-ci répond à « quelles pages renvoient une 404 sous la profondeur 3, et quels sont leurs titres ». C’est le node à utiliser quand la question est précise.

Trois points de conception comptent en pratique :

Les noms de champs sont vérifiés avant l’envoi de la requête. Le schéma d’Oncrawl est propre à chaque crawl et sensible à la casse : les champs disponibles dépendent de la configuration du crawl, et Status_Code n’est pas status_code. Le node lit d’abord le schéma du crawl, donc un champ erroné est signalé par son nom — avec des suggestions proches — au lieu de revenir sous forme d’erreur API générique.

Le plafond de 10 000 éléments appartient à un transport, pas à votre jeu de données. Oncrawl plafonne une requête de recherche à 10 000 éléments, quelle que soit la limite demandée. Avec la pagination automatique activée — c’est le réglage par défaut —, le node parcourt les pages tout seul jusqu’à obtenir les lignes demandées, et bascule de lui-même sur le transport d’export quand le plafond de recherche le bloque, jusqu’à une limite de sécurité de 100 000 lignes. Savoir quel transport s’applique n’est pas le travail de l’utilisateur.

Un résultat partiel dit toujours qu’il est partiel. Quoi qu’il ait arrêté la lecture — la limite demandée, le plafond dans les cas où il s’applique encore, une bascule de transport ratée —, provenance.complete et un avertissement explicite le disent. C’est important, car un résultat tronqué ressemble exactement à un résultat complet : un rapport construit sur les 10 000 premières lignes d’un jeu de quatre millions est faux sans en avoir l’air.

Cas d’usage courants :

• Lister toutes les pages en erreur, avec leur profondeur et leur titre, pour un audit SEO technique.
• Compter les pages par code de statut ou par profondeur sans télécharger la moindre ligne.
• Exporter un jeu de données de crawl complet vers un tableur.
• Examiner les liens internes ou le balisage de données structurées relevés pendant le crawl.
• Fournir à un LLM un ensemble de pages filtré et précis plutôt qu’un crawl entier.

Mise en place rapide#

Les trois modes#

Le choix du mode compte plus que tout autre réglage, car il s’agit de trois transports différents, qui ne sont pas soumis aux mêmes limites.

Mode	Renvoie	Limite	À utiliser quand
Lignes	Des enregistrements, paginés automatiquement	100 000 lignes avec la pagination automatique ; 10 000 sans elle, ou dès qu’un décalage est défini	Vous avez besoin des lignes elles-mêmes
Agrégations	Des décomptes calculés par Oncrawl	Aucune — rien n’est téléchargé ligne par ligne	Vous avez besoin de totaux, de distributions ou de répartitions
Export complet	Les lignes correspondantes en CSV ou JSONL diffusé	100 000 lignes ou 10 Mo, au premier atteint ; au-delà le fichier est coupé et truncated vaut true	Vous avez besoin des lignes correspondantes sous forme de fichier et le tri n’importe pas

La pagination automatique en mode Lignes#

L’API Data d’Oncrawl propose deux transports pour les lignes, et leurs règles diffèrent. Une requête de recherche renvoie du JSON paginé mais cesse de répondre au-delà de 10 000 éléments, quoi que demandent limit et offset. Une requête d’export n’a pas ce plafond, mais elle répond par un flux et refuse sort et offset.

Avec la pagination automatique activée, ce qui est le réglage par défaut, le node gère cette séparation lui-même. Il parcourt les pages de recherche jusqu’à obtenir les lignes demandées ; si le plafond de 10 000 éléments le bloque, il relit la même requête via le transport d’export et reconstitue les lignes à partir du flux, jusqu’à un maximum de 100 000 lignes. La sortie consigne la bascule par un avertissement indiquant que plus de 10 000 lignes correspondaient, que la lecture est passée automatiquement au transport d’export, et combien de lignes elle a finalement renvoyées.

Deux choses méritent d’être connues à propos de cette bascule. Un tri que vous auriez configuré est retiré, car le transport d’export le refuse — un avertissement le signale, et vous pouvez ordonner les lignes en aval. Et si la bascule échoue malgré les nouvelles tentatives, ou si l’export ne ramène pas plus de lignes que la recherche — il s’arrête à 10 Mo, que des lignes larges peuvent atteindre en premier —, les lignes déjà renvoyées par la recherche sont conservées, avec un avertissement précisant que le résultat est la recherche plafonnée. Perdre des données déjà lues serait pire que les livrer en les étiquetant comme partielles.

Le plafond de 100 000 lignes est une limite de sécurité du node, pas de l’API Oncrawl. Une lecture qui ne s’arrêterait qu’avec le jeu de données ferait entrer des millions de lignes dans une seule charge utile de workflow ; le plafond transforme cela en une troncature signalée.

Écrire un filtre OQL#

OQL est un objet JSON, pas une expression textuelle. Une condition simple est une feuille field, et les feuilles se composent avec and et or.

{ "field": ["status_code", "equals", 404] }

{
  "and": [
    { "field": ["status_code", "gte", 400] },
    { "field": ["depth", "between", [1, 4]] }
  ]
}

Opérateurs#

Groupe	Opérateurs	Remarques
Présence	has_value, has_no_value	Passez une chaîne vide comme valeur
Chaîne	equals, contains, startswith, endswith	Chacun accepte aussi le préfixe not_, par exemple not_contains
Numérique	gt, gte, lt, lte, between	between prend un tableau de deux valeurs ; borne basse incluse, borne haute exclue

Les opérateurs de chaîne acceptent un quatrième élément d’options : {"ci": true} pour une correspondance insensible à la casse, {"regex": true} si la valeur est une expression régulière.

{ "field": ["urlpath", "startswith", "/blog/([0-9]+)/", { "regex": true }] }

Paramètres de configuration#

Champs obligatoires#

Champs optionnels#

Sortie#

En mode Lignes :

{
  "provenance": {
    "crawl_id": "abc123",
    "data_type": "pages",
    "mode": "query",
    "offset": 0,
    "returned": 842,
    "total": 842,
    "complete": true,
    "truncated": false,
    "pagination": {
      "strategy": "search",
      "requests": 1,
      "auto_paginate": true
    },
    "warnings": [],
    "retrieved_at": "2026-10-20T14:00:00+00:00",
    "source": "Oncrawl API v2"
  },
  "rows": [{ "url": "/a", "status_code": 404 }]
}

Vérifiez toujours complete. C’est la réponse de référence à la question « cette lecture a-t-elle vu toutes les lignes correspondantes ? », et quand il vaut false, un avertissement explique ce qui a arrêté la lecture. truncated en est simplement l’inverse, conservé pour les workflows qui le lisent déjà.

Notez qu’honorer votre limite n’équivaut pas à être complet. Demander 10 lignes d’un filtre qui en fait correspondre 128 828 renvoie complete: false, avec un avertissement précisant que la lecture s’est arrêtée à la limite demandée alors que d’autres lignes correspondent, et invitant à augmenter la limite ou à resserrer le filtre OQL. C’est délibéré : le node rapporte ce qu’il a vu du jeu de données, pas s’il a bien fait ce qu’on lui demandait.

Le bloc pagination explique comment les lignes ont été obtenues : strategy vaut search ou export, requests compte les appels dépensés par le transport qui les a produites — utile quand une lecture est lente, un flux d’export comptant pour un seul appel — et auto_paginate reprend le réglage. Après une bascule sur le transport d’export, total conserve le décompte renvoyé par la recherche, le flux d’export n’en portant aucun.

Le mode Agrégations renvoie un tableau aggs avec la structure cols / rows d’Oncrawl. Le mode Export complet renvoie content, le fichier diffusé sous forme de texte, plus un line_count.

Résolution des problèmes#

Le champ 'status_kode' n'existe pas dans le schéma de ce crawl

Cause : Le nom du champ est mal orthographié, ou absent de la configuration de ce crawl.

Solution : Le message liste les correspondances proches — utilisez l’une d’elles. Le sélecteur Champs montre l’orthographe exacte pour ce crawl.

Vouliez-vous dire 'status_code' ? Les noms de champs sont sensibles à la casse

Cause : Le champ existe, mais avec une autre casse. Le schéma d’Oncrawl est sensible à la casse.

Solution : Reprenez l’orthographe exacte indiquée dans le message.

Le champ 'body_text' existe mais n'est pas filtrable dans ce crawl

Cause : Tous les champs du schéma ne sont pas filtrables ; Oncrawl indique lesquels le sont.

Solution : Le message liste les champs filtrables. Choisissez-en un, ou renvoyez le champ sans filtrer dessus.

L'opérateur 'contains' n'est pas disponible sur le champ 'fetched'

Cause : L’opérateur ne s’applique pas au type du champ — contains est un opérateur de chaîne, fetched est un booléen.

Solution : Le message liste les opérateurs que le crawl autorise sur ce champ.

Oncrawl plafonne une requête à 10 000 éléments, et ce plafond a été atteint

Cause : Plus de 10 000 lignes correspondaient, et la lecture n’a pas pu basculer sur le transport d’export qui lève le plafond — soit parce que la pagination automatique est désactivée, soit parce qu’un décalage est défini, ce que le transport d’export refuse. Le résultat est partiel.

Solution : Activez la pagination automatique et retirez le décalage : la lecture peut alors aller seule jusqu’à 100 000 lignes. Sinon, resserrez le filtre OQL, passez en Agrégations s’il ne vous faut que des décomptes, ou utilisez l’Export complet pour obtenir toutes les lignes sous forme de fichier.

La lecture s'est arrêtée à la limite demandée et d'autres lignes correspondent

Cause : La lecture a fait exactement ce que vous demandiez, mais votre filtre fait correspondre plus de lignes que la limite — le résultat est donc une tranche du jeu de données, pas le jeu de données. complete vaut false pour cette raison.

Solution : Augmentez la limite (jusqu’à 100 000 avec la pagination automatique), resserrez le filtre OQL, ou assumez la tranche comme un échantillon. provenance.total indique combien de lignes correspondent réellement.

Oncrawl refuse un décalage sur le transport d'export, la lecture n'a pas pu dépasser le plafond

Cause : Un décalage était défini sur une lecture qui avait besoin de plus de 10 000 lignes. Le transport d’export est le seul moyen de dépasser le plafond et il refuse un décalage : le node a donc gardé le décalage et le plafond.

Solution : Retirez le décalage. Il existe pour paginer manuellement, ce que la pagination automatique rend inutile ; sans lui, la lecture atteint jusqu’à 100 000 lignes d’un seul coup.

Oncrawl refuse un tri sur le transport d'export, l'ordre de tri a été retiré

Cause : La lecture a dépassé le plafond de 10 000 éléments et a basculé sur le transport d’export, qui n’accepte pas de tri.

Solution : Triez les lignes en aval, ou abaissez la limite sous 10 000 si l’ordre importe plus que le volume.

La lecture a tenté de dépasser le plafond via le transport d'export et cela a échoué

Cause : La bascule sur le transport d’export a échoué malgré les nouvelles tentatives du node, ou l’export n’a pas ramené plus de lignes que la recherche. Plutôt que de faire échouer l’exécution, le node a renvoyé les lignes que la recherche avait déjà lues, d’où truncated à true.

Solution : Relancez plus tard. Si l’avertissement indique que l’export n’a pas ramené plus de lignes que la recherche, sélectionnez moins de Champs pour alléger chaque ligne. Sinon, resserrez le filtre OQL pour que la lecture tienne sous 10 000 lignes et n’ait jamais besoin de la bascule.

'links' est un type de données volumineux et aucun filtre OQL n'a été fourni

Cause : links et structured_data contiennent couramment des millions de lignes, et la requête n’a aucun filtre.

Solution : Ajoutez un filtre OQL, ou passez en Agrégations. Parcourir des millions de liens ligne par ligne n’est pas viable.

Missing segmentation name in query

Cause : La requête fait référence à une segmentation — ce qu’Oncrawl appelle aussi des groupes de pages. Une segmentation est définie sur le projet, pas sur le crawl, et elle doit être nommée pour que ses groupes soient résolus. Ce node interroge les données d’un seul crawl : il n’a aucun emplacement pour en nommer une.

Le coupable est le plus souvent un champ sélectionné, pas le filtre : le schéma d’Oncrawl liste les champs de segmentation au milieu des autres, et en sélectionner un suffit à faire échouer toute la requête. Le node les masque désormais du sélecteur Champs et les refuse en les nommant avant l’appel ; cette erreur ne devrait donc plus venir que d’un filtre OQL écrit à la main, ou d’un node enregistré avant ce contrôle.

Solution : Retirez le champ de segmentation du filtre et des champs sélectionnés, et utilisez des champs de crawl classiques comme urlpath, depth ou status_code. Pour reproduire un groupe de pages, exprimez sa règle directement en OQL : un groupe couvrant un répertoire devient {"field": ["urlpath", "startswith", "/blog/"]}. Le message d’erreur renvoie la requête envoyée : c’est ainsi qu’on identifie le champ fautif.

Le crawl Oncrawl n'est pas terminé

Cause : Le crawl est encore en cours, ou il a échoué. Seul un crawl terminé possède des données interrogeables.

Solution : Attendez sa fin, ou utilisez un Oncrawl Crawl Resolver, qui ne renvoie que des crawls terminés.

Oncrawl a refusé la requête (403)

Cause : Oncrawl a reconnu le token mais refusé l’action. Le message reprend la raison donnée par Oncrawl :

• quota_error — le quota du compte ne permet pas la requête.
• no_active_subscription — le compte n’a pas d’abonnement actif.
• feature_not_available — l’offre n’inclut pas cette fonctionnalité, par exemple l’option API.
• sinon — il manque au token le scope projects:read, ou l’accès à ce projet.

Solution : Libérez ou augmentez le quota, renouvelez l’abonnement ou l’offre, ou régénérez le token avec le scope projects:read sur un compte qui voit le projet.

Limite de débit Oncrawl dépassée (429)

Cause : Oncrawl a répondu 429 à trois tentatives d’affilée. Le node relance une erreur 429 ou 5xx deux fois, à quelques secondes d’intervalle, avant d’abandonner. Oncrawl ne publie pas sa limite de débit.

Solution : Relancez plus tard, et évitez de lancer au même moment plusieurs workflows qui lisent Oncrawl.

Bonnes pratiques et pièges#

Comment s’intègre-t-il dans un workflow ?#

Une chaîne d’audit technique typique, avec le resolver qui maintient la fraîcheur des données :

graph LR
    Resolver[Oncrawl Crawl Resolver] --> Reader[Oncrawl Data Reader<br/>pages, status_code >= 400]
    Reader --> Extractor[JSON Path Extractor<br/>rows]
    Extractor --> LLM[LLM<br/>prioriser les corrections]
    LLM --> Email[Email Sender]

Nodes associés#