Docs
Anmelden

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)
Kein store-Flag pro Request

Storage-Delivery ist eine Eigenschaft des Crawlers, nicht des Pushs. Wenn der Crawler im Storage-Modus erstellt wurde, landet jedes Ergebnis automatisch in Cloud Storage - Sie müssen nicht bei jedem Push store=true setzen, und Webhook-Modus-Crawler können sich nicht pro Request anmelden.

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.

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

Die Push-Response ist klein - nur eine Bestätigung, dass die URL in der Queue ist.

{ "rid": "a1B2c3D4e5F6" }
Push-Durchsatz und Queue-Limits

Die Push-Rate ist standardmäßig auf 30 URLs/Sek. pro Token gedeckelt. Jeder Crawler fasst bis zu 100K URLs in seiner Warteschlange, und die Summe über alle Ihre Crawler hinweg ist auf 1.000.000 gedeckelt; sobald Sie diese überschreiten, pausieren Pushes und Sie erhalten eine E-Mail - leeren Sie die Queue (oder purgen) und Pushes laufen automatisch weiter.

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:

format=htmlformat=json
Content-Type: text/plainContent-Type: gzip/json
Body ist das HTML der SeiteBody ist JSON: { pc_status, original_status, rid, url, body }
Header tragen Metadaten: Original-Status, PC-Status, rid, urlHeader tragen dieselben Metadaten, die Felder befinden sich auch im Body

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.

Fehlgeschlagene Deliveries werden berechnet

Jeder Retry zählt für die Abrechnung als erfolgreicher Crawl - Crawlbase hat die Proxy-/Browser-Kosten bereits bezahlt. Halten Sie Ihren Webhook zuverlässig; der günstigste Weg, Credit-Verbrauch zu reduzieren, ist, keine Zustellungen mehr fallen zu lassen, nicht gegen die Retry-Policy anzukämpfen.

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.

Der Delivery-Modus wird bei der Erstellung festgelegt

Die beiden Modi sind exklusiv und werden bei der Erstellung an den Crawler gebunden. Ein Webhook-Crawler schreibt nicht in Storage; ein Storage-Crawler feuert keinen Webhook. Zum Wechseln erstellen Sie einen neuen Crawler im anderen Modus und migrieren Ihren Push-Traffic dorthin.

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

Token im Pfad, nicht im Query-String

Anders als die Crawling API erwarten diese Endpoints den Token im URL-Pfad. Bei JavaScript-Token-Crawlern tauschen Sie in jedem Beispiel unten den Normal token gegen Ihren JS-Token aus.

Stats

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

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'

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.

POSThttps://api.crawlbase.com/crawler/<TOKEN>/<NAME>/purge
curl -X POST 'https://api.crawlbase.com/crawler/YOUR_TOKEN/product-monitor/purge'
Purge ist sofort und total

Jede in diesem Crawler eingereihte URL wird verworfen - es gibt kein Soft-Delete und keine Wiederherstellung. Wenn Sie nur eine einzelne URL verwerfen müssen, verwenden Sie stattdessen Delete Job.

Einzelnen Job löschen

Eine einzelne URL aus der Queue per RID verwerfen - die Request-ID, die beim Pushen der URL zurückgegeben wurde.

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'

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

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

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

crawler
stringerforderlich
Name des Crawlers aus Ihrem Dashboard.
url
stringerforderlich (Push)
Einzureihende URL. URL-kodieren Sie sie.
callback_headers
stringoptional
Zusätzliche Header, die bei der Webhook-Zustellung mitgesendet werden, Format name|value|name|value. Nützlich, um IDs an Ihren Handler zurückzugeben. Nur für Webhook-Modus-Crawler - wird ignoriert, wenn der Crawler an Storage liefert.
queue_timeout
integer (Minuten)optional
Maximale Zeit, die der Request in der Queue verbleiben darf, bevor ihn ein Worker übernimmt. Bereich 110080 (1 Minute bis 7 Tage). Sobald ein Worker den Crawl startet, gilt dieser Timer nicht mehr. Wenn der Request beim Warten abläuft, erhalten Sie einen Callback mit HTTP 504 und pc_status=699. Weglassen (oder auf 0 setzen), um zu deaktivieren. Aggressive Werte erhöhen die Fehlerrate - wählen Sie, was widerspiegelt, wie lange das Ergebnis tatsächlich für Sie nützlich ist.
Alle Crawling API-Parameter
optional
Übergeben Sie page_wait, scroll, country, scraper usw. - sie werden auf jeden Crawl angewendet.

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.