Enterprise Crawler

Crawler 是一个托管队列，您将 URL 推入其中并从中读取结果。三个生命周期步骤 - Setup（配置队列）、Push（将 URL 入队）、Pull（接收结果） - 按顺序在下方介绍。

Setup

在您的 dashboard 中创建一个命名队列。每个 crawler 最多可容纳 10 万个 URL。为每个工作负载创建一个队列 - 它们之间不共享状态。创建时需要选择：

• 唯一的 名称（由您选择：product-monitor、news-feed 等）
• 投递模式：可以是回调 URL（Crawlbase 将每个结果 POST 到该 webhook）或 Cloud Storage（结果会自动持久化，您可按自己的节奏通过 Storage API 获取）。在创建时一次性选定；两种模式互斥 - 同一个 crawler 不能同时使用两者。
• token 类型（Normal 或 JavaScript）
• 并发上限（默认为 20，可应请求提高）

Push

将 URL 发送到 crawler 的队列。推送会立即返回一个 rid，让您的客户端继续后续工作；实际的爬取在后台按 crawler 配置的并发度进行。传递 callback=true 以让请求进入队列投递，而不是内联运行。

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

Push 响应很小 - 只是确认 URL 已入队。

{ "rid": "a1B2c3D4e5F6" }

Pull

已完成的爬取如何送达您。两种通道，在 crawler 创建时选定一次：

Webhook

当 crawler 是以回调 URL 创建时，每次爬取完成的瞬间，Crawlbase 都会将结果 POST 到该 webhook。body 在请求 body 中，元数据在请求 headers 中 - 无需轮询，无需客户端状态。

# 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

…

您的 webhook 应当：

• 可从 Crawlbase 服务器公开访问。
• 接受 POST，并在 200 毫秒内返回 200、201 或 204。
• 对 rid 保持幂等：重试时可能发生重复投递。
• 先确认再处理 - 如果处理时间超过响应窗口，请异步启动工作。

body 的形态遵循您在推送时设置的 format 参数：

两种形式都以 gzip 压缩（Content-Encoding: gzip）到达 - 您的处理程序需要在解析前先解压。例外是 Zapier webhooks，它无法读取 gzip 压缩的 body；Crawlbase 会检测 Zapier 回调 URL 并跳过压缩。

测试。当您第一次接入处理程序，想要查看真实 URL 的确切 payload 结构时，可以在 webhook crawler 旁边再创建一个 Storage 模式的 crawler，并将相同的 URL 推送到两者。通过 RID 从 Cloud Storage 拉取，您就有了一份冻结的参照，可用于与您的 webhook 接收内容进行比对 - 有助于在解压缩 bug 和元数据处理错误影响生产流量之前将其捕获。

监控机器人。Crawlbase 会按计划轮询您的 webhook 以检测中断。如果机器人无法访问您的端点或您停止返回 2xx，crawler 会 自动暂停自身，并在您的端点恢复后继续。该探测是一个常规的 POST，body 为 JSON，可通过 User-Agent 区分：

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

{ "monitor": true }

将探测视为无操作并返回 200。不要将其当作爬取结果来处理 - 没有真实的 RID 可供操作。

保护端点。使用随机字符串路径（yourdomain.com/2340JOiow43djoqe21rjosi）在实践中本身就已经是主要保护手段 - 该 URL 不太可能被发现。为了万无一失，再叠加以下一项或多项：

• 查询字符串 token：?token=…，webhook 在接受 body 之前先校验它。
• 在推送时通过 callback_headers 发送自定义 header（例如 X-Webhook-Token|s3kret），并在服务器端校验。
• 拒绝任何不是 POST 的请求。
• 拒绝任何缺失预期元数据 header（Pc-Status、Original-Status、rid）的请求。

我们不建议使用 IP 白名单 - Crawlbase 从许多 IP 推送，且这些 IP 会在不另行通知的情况下轮换。

Cloud Storage

当 crawler 是以 Storage 作为投递模式创建时，每个结果都会自动持久化到 Cloud Storage - 无需按 push 的标志，无需 webhook。您的消费端按自己的节奏通过 Storage API 获取结果。当下游是批处理的、当您无法运行 HTTPS 端点、或者当您想为每个已爬取的页面拥有一个稳定的 URL 时，请使用此模式。

推送方式与 webhook 模式的 crawler 完全相同 - 唯一的区别是结果的去向。一旦某个 URL 爬取完成，按 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 }'

要知道结果 何时 就绪，可以针对特定 RID 轮询 Find Job，关注 Stats 中的已入队 / 已完成计数，或者干脆按计划批量调用 /storage/bulk，让「RID not found」告诉您还有哪些尚在等待。

Management API

一组小型 REST 接口，用于监控和管理您的 crawler - 获取统计、清空队列、暂停 / 恢复、按 RID 查找或删除单个任务。所有 endpoint 都位于 /crawler/<TOKEN>/... 之下，并通过路径中的 token 进行认证（无需 query-string 中的 token）。

Stats

您所有 crawler 的汇总信息 - 并发数、队列深度、完成 / 失败计数，以及历史细分。

# 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

立即清空 crawler 的队列 - 所有仍处于待处理状态的 URL 都会被丢弃。可用于从失控的生产者中恢复，或清除您不再希望处理的批次。无法撤销。

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

删除单个任务

通过 RID 从队列中删除一个 URL - 即您推送 URL 时返回的 request ID。

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

按 RID 查找任务

查询某个请求的状态。如果仍在等待，则返回 QUEUED 以及入队时的元数据；如果已完成爬取（或从未进入队列），则返回 NOT_QUEUED。

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

暂停与恢复

让 crawler 停止接收新工作，同时保留其队列。推送的 URL 会继续入队，但 crawler 在您恢复之前不会处理它们。适用于维护窗口期，或当下游系统不健康时进行退避。

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

参数

何时使用 Crawler 与 API

• Crawler： 当���需要处理超过几百个 URL 时，尤其是跨越较长时间段。队列会处理重试、调度和并发。
• Direct Crawling API： 当您需要内联获取结果时 - 面向用户请求的页面渲染、AI agent 获取上下文等。