Enterprise Crawler

Le Crawler est une file gérée dans laquelle vous poussez des URL et dont vous lisez les résultats. Trois étapes du cycle de vie : Setup (configurer la file), Push (mettre des URL en file) et Pull (recevoir les résultats), traitées dans l'ordre ci-dessous.

Setup

Créez une file nommée dans votre dashboard. Chaque crawler peut contenir jusqu'à 100K URL. Créez une file par charge de travail : elles ne partagent pas d'état. À la création, vous choisissez :

• Un nom unique (vous le choisissez : product-monitor, news-feed, etc.)
• Un mode de livraison : soit une URL de callback (Crawlbase envoie chaque résultat en POST vers ce webhook), soit Cloud Storage (les résultats sont conservés automatiquement et vous les récupérez via le Storage API à votre propre rythme). Choisi une seule fois à la création ; les deux modes sont exclusifs : un même crawler ne fait pas les deux.
• Un type de token (Normal ou JavaScript)
• Une limite de concurrence (par défaut 20, augmentable sur demande)

Push

Envoyez des URL dans la file du crawler. Le push retourne immédiatement avec un rid pour que votre client puisse passer à autre chose ; le crawl effectif a lieu en arrière-plan selon la concurrence configurée du crawler. Passez callback=true pour orienter la requête vers la livraison par file plutôt que de l'exécuter en ligne.

curl 'https://api.crawlbase.com/?token=YOUR_TOKEN&crawler=product-monitor&callback=true&url=https%3A%2F%2Fexample.com%2Fp%2F12345'

from crawlbase import CrawlerAPI

api = CrawlerAPI({'token': 'YOUR_TOKEN'})
res = api.push(
    'https://example.com/p/12345',
    {'crawler': 'product-monitor'}
)
print(res['rid'])

const { CrawlerAPI } = require('crawlbase');
const api = new CrawlerAPI({ token: 'YOUR_TOKEN' });

const res = await api.push(
  'https://example.com/p/12345',
  { crawler: 'product-monitor' }
);
console.log(res.rid);

La réponse au push est courte : juste une confirmation que l'URL est mise en file.

{ "rid": "a1B2c3D4e5F6" }

Pull

Comment les crawls terminés vous parviennent. Deux canaux, choisis une seule fois à la création du crawler :

Webhook

Lorsque le crawler a été créé avec une URL de callback, Crawlbase envoie chaque résultat en POST vers ce webhook dès que le crawl se termine. Le body dans le corps de la requête, les métadonnées dans les en-têtes : pas de polling, pas d'état côté client.

# POST https://your-app.com/webhook
# Content-Type: text/html  (or application/json if scraper used)
# pc_status: 200
# original_status: 200
# rid: a1B2c3D4e5F6
# url: https://example.com/p/12345

…

Votre webhook doit :

• Être accessible publiquement depuis les serveurs de Crawlbase.
• Accepter POST et répondre avec 200, 201 ou 204 en moins de 200 ms.
• Soyez idempotent sur rid : des livraisons en double peuvent se produire lors de réessais.
• Acquittez avant de traiter : lancez le travail en async s'il prend plus longtemps que la fenêtre de réponse.

La forme du body suit le paramètre format que vous définissez au push :

Les deux formats arrivent compressés en gzip (Content-Encoding: gzip) : votre handler doit décompresser avant de parser. L'exception concerne les webhooks Zapier, qui ne savent pas lire les corps gzippés ; Crawlbase détecte les URL de callback Zapier et ignore la compression.

Tests. Lorsque vous branchez le handler pour la première fois et que vous voulez inspecter la forme exacte du payload pour une vraie URL, créez un crawler en mode Storage en parallèle de votre crawler webhook et poussez les mêmes URL dans les deux. Récupérez depuis Cloud Storage par RID et vous disposez d'une référence figée à comparer aux réceptions de votre webhook : utile pour détecter les bugs de décompression et les erreurs de gestion des métadonnées avant qu'ils n'atteignent le trafic de production.

Bot de surveillance. Crawlbase interroge votre webhook selon une cadence régulière pour détecter les pannes. Si le bot ne peut pas joindre votre endpoint ou si vous cessez de retourner du 2xx, le crawler se met automatiquement en pause et reprend dès que votre endpoint redevient disponible. La sonde est un POST classique avec un body JSON, identifiable par son User-Agent :

POST https://your-app.com/webhook
User-Agent: Crawlbase Monitoring Bot 1.0
Content-Type: application/json

{ "monitor": true }

Traitez les sondes comme un no-op et renvoyez 200. Ne les traitez pas comme des résultats de crawl : il n'y a pas de vrai RID sur lequel agir.

Protéger l'endpoint. Un chemin avec une chaîne aléatoire (yourdomain.com/2340JOiow43djoqe21rjosi) constitue déjà l'essentiel de la protection en pratique : l'URL a peu de chances d'être découverte. Pour plus de sécurité, ajoutez une ou plusieurs des couches suivantes :

• Un token en query-string : ?token=… que le webhook vérifie avant d'accepter le body.
• Un en-tête personnalisé envoyé via callback_headers au push (par ex. X-Webhook-Token|s3kret) et vérifié côté serveur.
• Rejetez tout ce qui n'est pas POST.
• Rejetez tout ce qui ne contient pas les en-têtes de métadonnées attendus (Pc-Status, Original-Status, rid).

Nous ne recommandons pas l'allowlisting d'IP : Crawlbase pousse depuis de nombreuses IPs et l'ensemble change sans préavis.

Cloud Storage

Lorsque le crawler a été créé avec Storage comme mode de livraison, chaque résultat est conservé automatiquement dans Cloud Storage : pas de flag par push, pas de webhook. Votre consommateur récupère les résultats à son propre rythme via le Storage API. À utiliser quand le traitement aval est en batch, quand vous ne pouvez pas exécuter un endpoint HTTPS, ou quand vous voulez une URL stable pour chaque page crawlée.

Poussez de la même manière que pour un crawler en mode webhook : la seule différence est l'endroit où le résultat finit. Une fois le crawl d'une URL terminé, récupérez-la par RID :

# Single fetch by RID
curl 'https://api.crawlbase.com/storage?token=YOUR_TOKEN&rid=a1B2c3D4e5F6'

# Or batch-drain up to 100 RIDs at once with auto_delete=true
# so storage stays small.
curl -X POST 'https://api.crawlbase.com/storage/bulk?token=YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "rids": ["RID1","RID2","RID3"], "auto_delete": true }'

Pour savoir quand un résultat est prêt, soit interrogez Find Job pour un RID donné, soit surveillez Stats pour les compteurs de tâches en file / terminées, soit videz simplement par lots /storage/bulk selon une cadence régulière et laissez « RID not found » vous indiquer ce qui est encore en attente.

Management API

Une petite surface REST pour surveiller et gérer vos crawlers : obtenir des stats, purger une file, mettre en pause/reprendre, trouver ou supprimer un job individuel par RID. Tous les endpoints se trouvent sous /crawler/<TOKEN>/... et s'authentifient par token dans le chemin (pas besoin de token dans la query string).

Stats

Récapitulatif sur l'ensemble de vos crawlers : concurrence, profondeur de file, nombre de jobs terminés/échoués, et ventilation par historique.

# All-time summary
curl 'https://api.crawlbase.com/crawler/YOUR_TOKEN/stats'

# Same, filtered to a date range (YYYY-MM-DD bounds, inclusive)
curl 'https://api.crawlbase.com/crawler/YOUR_TOKEN/stats?history_from=2026-04-01&history_to=2026-04-30'

Purger un crawler

Vide immédiatement la file du crawler : toutes les URL encore en attente sont supprimées. À utiliser pour récupérer après un producteur emballé ou pour vider un batch que vous ne voulez plus traiter. Pas de retour en arrière possible.

curl -X POST 'https://api.crawlbase.com/crawler/YOUR_TOKEN/product-monitor/purge'

Supprimer un job individuel

Supprime une URL de la file par son RID : l'identifiant de requête renvoyé lors du push de l'URL.

curl -X POST 'https://api.crawlbase.com/crawler/YOUR_TOKEN/product-monitor/delete_job?rid=YOUR_RID'

Trouver un job par RID

Vérifiez où en est une requête. Renvoie QUEUED avec les métadonnées de mise en file si elle est encore en attente, ou NOT_QUEUED si elle a déjà été crawlée (ou n'a jamais été placée dans la file).

curl 'https://api.crawlbase.com/crawler/YOUR_TOKEN/product-monitor/find_by_rid/YOUR_RID'

{
  "status": "QUEUED",
  "request_info": {
    "rid": "YOUR_RID",
    "url": "YOUR_URL",
    "retry": 3,
    "created_at": 1600494969.189415
  }
}

{
  "status": "NOT_QUEUED",
  "request_info": {
    "rid": "YOUR_RID"
  }
}

Pause et reprise

Empêche un crawler de prendre du nouveau travail sans perdre sa file. Les URL poussées continuent d'être mises en file, mais le crawler arrête de les traiter jusqu'à ce que vous repreniez. Utile pour les fenêtres de maintenance ou pour lever le pied lorsqu'un système en aval n'est pas en bonne santé.

# Pause - stops the crawler picking up new work
curl -X POST 'https://api.crawlbase.com/crawler/YOUR_TOKEN/product-monitor/pause'

# Unpause - resumes processing
curl -X POST 'https://api.crawlbase.com/crawler/YOUR_TOKEN/product-monitor/unpause'

Paramètres

Quand utiliser le Crawler plutôt que l'API

• Crawler : dès que vous avez plus de quelques centaines d'URL à traiter, surtout sur de longues périodes. La file gère les nouvelles tentatives, l'ordonnancement et la concurrence.
• Crawling API directe : quand vous avez besoin du résultat en ligne : rendu de page pour une requête utilisateur, agent IA récupérant du contexte, etc.