Enterprise Crawler

Der Crawler ist eine verwaltete Queue, in die Sie URLs pushen und aus der Sie Ergebnisse auslesen. Drei Lifecycle-Schritte — Setup (Queue konfigurieren), Push (URLs einreihen), Pull (Ergebnisse empfangen) — werden im Folgenden der Reihe nach behandelt.

Setup

Erstellen Sie eine benannte Queue in Ihrem Dashboard. Jeder Crawler fasst bis zu 100.000 URLs. Erstellen Sie eine Queue pro Workload — sie teilen keinen State. Bei der Erstellung wählen Sie:

• Einen eindeutigen Namen (frei wählbar: product-monitor, news-feed usw.)
• Einen Delivery-Modus — entweder eine Callback-URL (Crawlbase POSTet jedes Ergebnis an diesen Webhook) oder Cloud Storage (Ergebnisse werden automatisch persistiert und Sie holen sie über die Storage API in Ihrem eigenen Rhythmus ab). Einmalig bei der Erstellung festgelegt; die beiden Modi sind exklusiv — derselbe Crawler macht nicht beides.
• Einen Token-Typ (Normal oder JavaScript)
• Ein Concurrency-Limit (Standard 20, auf Anfrage erhöhbar)

Push

Senden Sie URLs an die Queue des Crawlers. Der Push kehrt sofort mit einer rid zurück, sodass Ihr Client weiterarbeiten kann; der eigentliche Crawl läuft im Hintergrund mit der konfigurierten Concurrency des Crawlers ab. Übergeben Sie callback=true, um den Request der Queue-Delivery zuzuweisen, statt ihn inline auszuführen.

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

Die Push-Response ist klein — nur eine Bestätigung, dass die URL eingereiht wurde.

{ "rid": "a1B2c3D4e5F6" }

Pull

Wie abgeschlossene Crawls zu Ihnen gelangen. Zwei Kanäle, einmalig bei der Erstellung des Crawlers festgelegt:

Webhook

Wenn der Crawler mit einer Callback-URL erstellt wurde, POSTet Crawlbase jedes Ergebnis an diesen Webhook, sobald der Crawl abgeschlossen ist. Body im Request-Body, Metadaten in den Request-Headern — kein Polling, kein clientseitiger State.

# 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

…

Ihr Webhook sollte:

• Öffentlich von den Crawlbase-Servern erreichbar sein.
• POST akzeptieren und innerhalb von 200 ms mit 200, 201 oder 204 antworten.
• Idempotent bezüglich rid sein — Duplikat-Deliveries können bei Retries auftreten.
• Vor der Verarbeitung quittieren — starten Sie die Arbeit async, falls sie länger als das Response-Fenster dauert.

Die Body-Form folgt dem format-Parameter, den Sie beim Push setzen:

Beide Formen treffen gzip-komprimiert ein (Content-Encoding: gzip) — Ihr Handler muss vor dem Parsen dekomprimieren. Ausnahme sind Zapier-Webhooks, die keine gzip-Bodies lesen können; Crawlbase erkennt Zapier-Callback-URLs und überspringt die Komprimierung.

Testing. Wenn Sie den Handler zum ersten Mal verdrahten und die exakte Payload-Form für eine echte URL inspizieren möchten, erstellen Sie parallel zu Ihrem Webhook-Crawler einen Storage-Modus-Crawler und pushen Sie dieselben URLs an beide. Holen Sie das Ergebnis per RID aus Cloud Storage ab, und Sie haben eine eingefrorene Referenz, gegen die Sie Ihre Webhook-Empfänge vergleichen können — nützlich, um Dekomprimierungsfehler und Fehler beim Metadaten-Handling zu finden, bevor sie den Produktionstraffic erreichen.

Monitoring-Bot. Crawlbase pollt Ihren Webhook nach einem Zeitplan, um Ausfälle zu erkennen. Wenn der Bot Ihren Endpoint nicht erreichen kann oder Sie keine 2xx mehr zurückgeben, pausiert sich der Crawler selbst automatisch und nimmt die Arbeit wieder auf, sobald Ihr Endpoint zurück ist. Die Probe ist ein normaler POST mit einem JSON-Body, erkennbar am User-Agent:

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

{ "monitor": true }

Behandeln Sie Probes als No-Op und geben Sie 200 zurück. Verarbeiten Sie sie nicht als Crawl-Ergebnisse — es gibt keine echte RID, auf die Sie reagieren könnten.

Endpoint absichern. Ein zufälliger String-Pfad (yourdomain.com/2340JOiow43djoqe21rjosi) ist in der Praxis bereits ein Großteil des Schutzes — die URL wird kaum entdeckt. Für mehr Sicherheit kombinieren Sie eine oder mehrere Maßnahmen:

• Ein Query-String-Token: ?token=…, das der Webhook prüft, bevor er den Body akzeptiert.
• Ein Custom-Header, gesendet via callback_headers beim Push (z. B. X-Webhook-Token|s3kret) und serverseitig verifiziert.
• Alles ablehnen, was nicht POST ist.
• Alles ablehnen, dem die erwarteten Metadaten-Header fehlen (Pc-Status, Original-Status, rid).

IP-Allowlisting empfehlen wir nicht — Crawlbase pusht von vielen IPs aus, und der Pool rotiert ohne Vorankündigung.

Cloud Storage

Wenn der Crawler mit Storage als Delivery-Modus erstellt wurde, wird jedes Ergebnis automatisch in Cloud Storage persistiert — kein Flag pro Push, kein Webhook. Ihr Consumer holt die Ergebnisse in seinem eigenen Rhythmus über die Storage API ab. Verwenden Sie das, wenn nachgelagerte Systeme im Batch arbeiten, wenn Sie keinen HTTPS-Endpoint betreiben können oder wenn Sie eine stabile URL für jede gecrawlte Seite haben möchten.

Pushen Sie genau so wie bei einem Webhook-Modus-Crawler — der einzige Unterschied liegt darin, wo das Ergebnis landet. Sobald eine URL fertig gecrawlt ist, holen Sie sie per RID ab:

# 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 }'

Um zu wissen, wann ein Ergebnis bereit ist, können Sie entweder Find Job für eine bestimmte RID pollen, Stats auf die Counter queued / completed beobachten oder einfach /storage/bulk nach Zeitplan im Batch leeren und sich von „RID nicht gefunden" sagen lassen, was noch aussteht.

Management API

Eine kleine REST-Oberfläche zum Monitoring und Management Ihrer Crawler — Stats abrufen, eine Queue purgen, pausieren/fortsetzen, einen einzelnen Job per RID finden oder löschen. Alle Endpoints liegen unter /crawler/<TOKEN>/... und authentifizieren sich per Token im Pfad (kein Token im Query-String erforderlich).

Stats

Übersicht über alle Ihre Crawler — Concurrency, Queue-Tiefe, Anzahl abgeschlossener/fehlgeschlagener Crawls und ein History-Breakdown.

# 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'

Crawler purgen

Leert die Queue des Crawlers sofort — jede noch ausstehende URL wird verworfen. Nutzen Sie das, um sich von einem ausgerasteten Producer zu erholen oder einen Batch zu löschen, den Sie nicht mehr verarbeiten möchten. Es gibt kein Undo.

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

Einzelnen Job löschen

Entfernen Sie eine URL über ihre RID aus der Queue — die Request-ID, die beim Pushen der URL zurückgegeben wurde.

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

Job per RID finden

Sehen Sie nach, wo ein Request steht. Gibt QUEUED mit den Queue-Metadaten zurück, wenn er noch aussteht, oder NOT_QUEUED, wenn er bereits gecrawlt wurde (oder es nie in die Queue geschafft hat).

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"
  }
}

Pausieren und fortsetzen

Verhindert, dass ein Crawler neue Arbeit aufnimmt, ohne seine Queue zu verlieren. Gepushte URLs werden weiterhin eingereiht, aber der Crawler verarbeitet sie erst weiter, wenn Sie ihn fortsetzen. Nützlich für Wartungsfenster oder zum Zurückfahren, wenn ein nachgelagertes System angeschlagen ist.

# 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'

Parameter

Wann Crawler vs. die API verwenden

• Crawler: immer dann, wenn Sie mehr als ein paar hundert URLs zu verarbeiten haben, besonders über lange Zeiträume hinweg. Die Queue übernimmt Retries, Scheduling und Concurrency.
• Direkte Crawling API: wenn Sie das Ergebnis inline benötigen — Page-Rendering für einen User-facing Request, ein KI-Agent, der Kontext abholt, usw.