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) - im Folgenden der Reihe nach behandelt.

Setup

Erstellen Sie eine benannte Queue in Ihrem Dashboard. Jeder Crawler fasst bis zu 100K 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 sendet jedes Ergebnis per POST an diesen Webhook) oder Cloud Storage (Ergebnisse werden automatisch persistiert und Sie holen sie nach Ihrem eigenen Zeitplan über die Storage API ab). Wird einmalig bei der Erstellung festgelegt; die beiden Modi schließen sich gegenseitig aus - derselbe Crawler kann 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 in der Queue ist.

{ "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, sendet Crawlbase jedes Ergebnis per POST 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.
• Seien Sie idempotent bezüglich rid: Doppelte Zustellungen können bei Retries vorkommen.
• Bestätigen Sie vor der Verarbeitung - 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 Formate kommen gzip-komprimiert an (Content-Encoding: gzip) - Ihr Handler muss vor dem Parsen dekomprimieren. Die Ausnahme sind Zapier-Webhooks, die keine gzip-komprimierten Bodies lesen können; Crawlbase erkennt Zapier-Callback-URLs und überspringt die Komprimierung.

Testen. Wenn Sie den Handler zum ersten Mal verkabeln und die genaue Payload-Form für eine echte URL inspizieren möchten, erstellen Sie zusätzlich zu Ihrem Webhook-Crawler einen Storage-Modus-Crawler und pushen Sie dieselben URLs an beide. Holen Sie aus Cloud Storage per RID ab, und Sie haben eine eingefrorene Referenz, gegen die Sie Ihre Webhook-Empfänge vergleichen können - nützlich, um Dekomprimierungs-Bugs und Metadaten-Handhabungsfehler abzufangen, bevor sie den Produktiv-Traffic 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.

Schutz des Endpoints. Ein Pfad aus einem zufälligen String (yourdomain.com/2340JOiow43djoqe21rjosi) ist in der Praxis bereits der Großteil des Schutzes - die URL wird kaum entdeckt werden. Für doppelte Absicherung kombinieren Sie eines oder mehrere der folgenden:

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

Wir empfehlen kein IP-Allowlisting - Crawlbase pusht von vielen IPs aus, und das Set 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 Ergebnisse nach seinem eigenen Zeitplan über die Storage API ab. Verwenden Sie das, wenn die nachgelagerte Verarbeitung gebatcht ist, wenn Sie keinen HTTPS-Endpoint betreiben können oder wenn Sie eine stabile URL für jede gecrawlte Seite haben möchten.

Pushen Sie genauso, wie Sie es für einen Webhook-Modus-Crawler tun würden - der einzige Unterschied ist, 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 Überwachen und Verwalten 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 Query-String-Token erforderlich).

Stats

Zusammenfassung über alle Ihre Crawler hinweg - Concurrency, Queue-Tiefe, Anzahl abgeschlossen/fehlgeschlagen und eine History-Aufschlüsselung.

# 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. Verwenden Sie das, um sich von einem außer Kontrolle geratenen Producer zu erholen oder um 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

Eine einzelne URL aus der Queue per RID verwerfen - 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 - Seiten-Rendering für einen Benutzer-Request, ein AI-Agent, der Kontext abruft, usw.