Enterprise Crawler

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

Setup

在您的 dashboard 中创建一个命名队列。每个 crawler 最多可容纳 100K 个 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 在请求体中，元数据在请求头中——无需轮询，无需客户端状态。

# 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 webhook，它无法读取 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——无需按推送设置标志，无需 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 查找或删除单个任务。所有端点都位于 /crawler/<TOKEN>/... 之下，并通过路径中的 token 进行认证（无需查询字符串中的 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 时返回的请求 ID）从队列中丢弃一个 URL。

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 代理获取上下文等。