Enterprise Crawler

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

Setup

Créez une file nommée dans votre tableau de bord. Chaque crawler peut contenir jusqu'à 100K URL. Créez une file par charge de travail — elles ne partagent pas leur é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 à ce webhook), soit Cloud Storage (les résultats sont conservés automatiquement et vous les récupérez via la Storage API selon 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 du push est légère — juste une confirmation que l'URL est 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 sur ce webhook dès que le crawl se termine. Le contenu est dans le body 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.
• Être idempotent sur rid — des livraisons en double peuvent survenir lors d'un réessai.
• Accuser réception avant tout traitement — lancez le travail en async s'il prend plus de temps que la fenêtre de réponse.

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

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

Tests. Lorsque vous configurez le handler pour la première fois et souhaitez inspecter la forme exacte du payload pour une URL réelle, créez un crawler en mode Storage en parallèle de celui en webhook et poussez les mêmes URL aux deux. Récupérez depuis Cloud Storage par RID et vous disposez d'une référence figée à comparer aux livraisons reçues sur votre webhook — utile pour repérer les bugs de décompression et les erreurs de gestion des métadonnées avant qu'ils n'atteignent la 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 retournez 200. Ne les traitez pas comme des résultats de crawl — il n'y a pas de RID réel 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 une sécurité supplémentaire, 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 le filtrage par liste d'IP — Crawlbase pousse depuis de nombreuses IP 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 la Storage API. Utilisez ce mode lorsque l'aval fonctionne par lots, lorsque vous ne pouvez pas exécuter d'endpoint HTTPS, ou lorsque vous souhaitez disposer d'une URL stable pour chaque page crawlée.

Poussez de la même façon que pour un crawler en mode webhook — la seule différence est l'endroit où le résultat aboutit. Une fois qu'une URL a fini d'être crawlée, 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 statistiques, 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 via le token dans le chemin (pas besoin de token en query string).

Stats

Récapitulatif sur l'ensemble de vos crawlers — concurrence, profondeur de file, nombre de tâches terminées/échouées et un détail 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 — toute URL encore en attente est supprimée. Utilisez ceci pour récupérer après un producteur emballé ou pour effacer un lot que vous ne souhaitez 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

Retirez une URL de la file via son RID — l'identifiant de requête renvoyé lorsque vous avez poussé 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 : lorsque vous avez besoin du résultat en ligne — rendu de page pour une requête utilisateur, agent IA récupérant du contexte, etc.