爬取

爬取会将一个 URL 提交给 Firecrawl，并递归发现和抓取所有可到达的子页面。它会自动处理 sitemap、JavaScript 渲染和速率限制，并为每个页面返回干净的 Markdown 或结构化数据。

• 通过 sitemap 和递归链接遍历发现页面
• 支持路径过滤、深度限制以及对子域名/外部链接的控制
• 通过轮询、WebSocket 或 webhook 返回结果

调用 POST /v2/crawl 并提供起始 URL，即可提交爬取任务。该端点会返回一个任务 ID，你可以用它轮询结果。

Scrape 端点的所有选项都可通过 scrapeOptions (JS) / scrape_options (Python) 在 crawl 中使用。它们将应用于爬虫抓取的每个页面，包括 formats、代理、缓存、actions、location 和 tags。

from firecrawl import Firecrawlfirecrawl = Firecrawl(api_key='fc-YOUR_API_KEY')# 使用 scrape 选项进行爬取response = firecrawl.crawl('https://example.com',    limit=100,    scrape_options={        'formats': [            'markdown',            { 'type': 'json', 'schema': { 'type': 'object', 'properties': { 'title': { 'type': 'string' } } } }        ],        'proxy': 'auto',        'max_age': 600000,        'only_main_content': True    })

使用任务 ID 轮询爬取状态并获取结果。

响应会根据爬取任务的状态而有所不同。对于未完成的任务或超过 10MB 的大型响应，会返回一个 next URL 参数。你需要请求该 URL 以获取后续的每 10MB 数据。如果没有 next 参数，则表示爬取数据已结束。

通过 SDK 使用 crawl 有两种方式。

crawl 方法会等待爬取完成并返回完整响应。自动处理分页。适用于大多数场景，推荐使用。

响应包括爬取状态及所有抓取到的数据：

startCrawl / start_crawl 方法会立即返回一个爬取 ID。随后你需要手动轮询状态。这适合长时间运行的爬取任务或自定义轮询逻辑。

初始响应会返回任务 ID：

{  "success": true,  "id": "123-456-789",  "url": "https://api.firecrawl.dev/v2/crawl/123-456-789"}

watcher 方法会在页面爬取过程中提供实时更新。启动爬取后，订阅事件即可进行即时数据处理。

你可以配置 webhook，在爬取过程中实时接收通知，从而在页面被抓取后立即进行处理，而无需等待整个爬取任务完成。

curl -X POST https://api.firecrawl.dev/v2/crawl \    -H 'Content-Type: application/json' \    -H 'Authorization: Bearer YOUR_API_KEY' \    -d '{      "url": "https://docs.firecrawl.dev",      "limit": 100,      "webhook": {        "url": "https://your-domain.com/webhook",        "metadata": {          "any_key": "any_value"        },        "events": ["started", "page", "completed"]      }    }'

{  "success": true,  "type": "crawl.page",  "id": "crawl-job-id",  "data": [...], // 'page' 事件的页面数据  "metadata": {}, // Your custom metadata  "error": null}

来自 Firecrawl 的每个 webhook 请求都会包含一个 X-Firecrawl-Signature 请求头，其中含有一个 HMAC-SHA256 签名。务必验证此签名，以确保 webhook 为真实请求且未被篡改。

1. 在账户设置中的 Advanced (高级) 选项卡 获取你的 webhook 密钥 (secret)
2. 从 X-Firecrawl-Signature 请求头中提取签名
3. 使用该密钥对原始请求体计算 HMAC-SHA256
4. 使用时间安全函数 (timing-safe function) 将计算结果与签名请求头中的值进行比较

有关 JavaScript 和 Python 的完整实现示例，请参阅 Webhook 安全文档。如需查看更全面的 webhook 文档，包括详细的事件负载、负载结构、高级配置和故障排查，请参阅 Webhooks 文档。

提交爬取任务时可用的完整参数集：

• sitemap 发现：默认情况下，爬虫会包含网站的 sitemap 来发现 URL (sitemap: "include") 。如果设置 sitemap: "skip"，则只会发现可通过根 URL 的 HTML 链接访问到的页面。像 PDF 这类资源，或列在 sitemap 中但未在 HTML 中直接链接的深层页面，都会被遗漏。为了获得最大覆盖率，建议保留默认设置。
• 额度消耗：每爬取一个页面消耗 1 个额度。JSON 模式每页额外消耗 4 个额度，PDF 解析则每个 PDF 页面消耗 1 个额度。
• 结果过期时间：任务结果在完成后的 24 小时内可通过 API 获取。此后，请在活动日志中查看结果。
• 爬取错误：data 数组包含 Firecrawl 成功抓取的页面。使用 Get Crawl Errors 端点可获取因网络错误、超时或被 robots.txt 封禁而失败的页面。

• 外部链接：设置 allowExternalLinks: true 后，爬虫会跟随指向域名外部的链接，并对每个链接页面抓取一次——不会继续爬取这些外部页面中的链接。指向外部站点主页的链接 (不含路径的根 URL，例如 https://example.com/) 会被特意跳过，以避免抓取整个无关站点；这些链接会以代码 EXTERNAL_LINK 显示在 Get Crawl Errors 中。重定向会被跟随至其目标地址——包括解析为其规范 URL 的链接 (例如 http → https 或 www 变体) ——因此，只有最终跳转至外部主页的重定向会被跳过。

• 非确定性结果：同一配置在多次运行之间的爬取结果可能会有所不同。页面会并发抓取，因此链接被发现的顺序取决于网络时序以及哪些页面先完成加载。这意味着在接近深度边界时，站点的不同分支可能会被探索到不同程度，尤其是在 maxDiscoveryDepth 值较高时。要获得更稳定的结果，请将 maxConcurrency 设置为 1，或者在站点拥有完整 sitemap 时使用 sitemap: "only"。

你是需要 Firecrawl API 密钥的 AI 代理吗？请参阅 firecrawl.dev/agent-onboarding/SKILL.md 了解自动化接入说明。