Docs
Se connecter

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)
Pas de flag store par requête

La livraison via Storage est une propriété du crawler, pas du push. Si le crawler a été créé en mode Storage, chaque résultat arrive automatiquement dans Cloud Storage — vous n'avez pas besoin de définir store=true à chaque push, et les crawlers en mode webhook ne peuvent pas l'activer requête par requête.

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.

GEThttps://api.crawlbase.com/?token=…&crawler=NAME&callback=true&url=…
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" }
Débit de push et limites de file

Le débit de push est plafonné à 30 URL/s par token par défaut. Chaque crawler peut contenir jusqu'à 100K URL dans sa file d'attente, et le total cumulé sur l'ensemble de vos crawlers est plafonné à 1 000 000 ; une fois ce seuil dépassé, les pushes sont mis en pause et vous recevez un e-mail — videz la file (ou purgez) et les pushes reprennent automatiquement.

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 :

format=htmlformat=json
Content-Type: text/plainContent-Type: gzip/json
Le body est le HTML de la pageLe body est du JSON : { pc_status, original_status, rid, url, body }
Les en-têtes portent les métadonnées : Original-Status, PC-Status, rid, urlLes en-têtes portent les mêmes métadonnées, les champs sont aussi présents dans le body

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.

Les livraisons échouées sont facturées

Chaque réessai compte comme un crawl réussi pour la facturation — Crawlbase a déjà payé le coût du proxy / navigateur. Gardez votre webhook fiable ; la façon la moins chère de réduire la consommation de crédits est d'arrêter de perdre des livraisons, pas de combattre la politique de réessai.

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.

Le mode de livraison est défini à la création

Les deux modes sont exclusifs et liés au crawler au moment de sa création. Un crawler en mode webhook n'écrit pas dans Storage ; un crawler en mode Storage ne déclenche pas de webhook. Pour changer, créez un nouveau crawler avec l'autre mode et migrez votre trafic push vers celui-ci.

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).

Token dans le chemin, pas en query string

Contrairement à la Crawling API, ces endpoints attendent le token dans le chemin de l'URL. Pour les crawlers utilisant un JavaScript token, remplacez le Normal token par votre JS token dans chaque exemple ci-dessous.

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.

GEThttps://api.crawlbase.com/crawler/<TOKEN>/stats
# 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.

POSThttps://api.crawlbase.com/crawler/<TOKEN>/<NAME>/purge
curl -X POST 'https://api.crawlbase.com/crawler/YOUR_TOKEN/product-monitor/purge'
La purge est immédiate et totale

Toute URL en file dans ce crawler est supprimée — pas de soft-delete, pas de récupération. Si vous souhaitez supprimer une seule URL, utilisez plutôt Delete Job.

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.

POSThttps://api.crawlbase.com/crawler/<TOKEN>/<NAME>/delete_job
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).

GEThttps://api.crawlbase.com/crawler/<TOKEN>/<NAME>/find_by_rid/<RID>
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

crawler
stringobligatoire
Nom du crawler tel qu'affiché dans votre dashboard.
url
stringobligatoire (push)
URL à mettre en file. Encodez-la en URL.
callback_headers
stringoptionnel
En-têtes supplémentaires à inclure lors de la livraison du webhook, format name|value|name|value. Utile pour renvoyer des identifiants à votre handler. Crawlers en mode webhook uniquement — ignoré lorsque le crawler livre vers Storage.
queue_timeout
integer (minutes)optionnel
Durée maximale pendant laquelle la requête peut rester en file avant qu'un worker la prenne en charge. Plage 110080 (de 1 minute à 7 jours). Une fois qu'un worker démarre le crawl, ce minuteur ne s'applique plus. Si la requête expire en attente, vous recevez un callback avec HTTP 504 et pc_status=699. Omettez (ou définissez à 0) pour désactiver. Des valeurs agressives augmentent le taux d'échec — choisissez ce qui reflète la durée réelle pendant laquelle le résultat vous est utile.
Tous les paramètres de la Crawling API
optionnel
Passez page_wait, scroll, country, scraper, etc. — ils sont appliqués à chaque crawl.

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.