跳转到主要内容
涵盖 Firecrawl 的 抓取、爬取、map 和 代理 各端点下所有选项的参考说明。

基础抓取

要抓取单个页面并获取干净的 Markdown 内容,请使用 /scrape 端点。

抓取 PDF

Firecrawl 支持 PDF。需要确保解析 PDF 时,请使用 parsers 选项(例如 parsers: ["pdf"])。你可以通过 mode 选项来控制解析策略:
  • auto(默认)— 先尝试基于文本的快速提取,如有需要再回退到 OCR。
  • fast — 仅进行基于文本(嵌入文本)的解析。速度最快,但会跳过扫描件或图片较多的页面。
  • ocr — 对每一页强制使用 OCR 解析。适用于扫描文档,或在 auto 误判页面类型时使用。
{ type: "pdf" }"pdf" 都默认使用 mode: "auto"

抓取选项

使用 /scrape 端点时,你可以通过以下选项来自定义请求。

Formats (formats)

formats 数组控制抓取器返回哪些输出类型。默认值:["markdown"] 字符串 formats:直接传入名称 (例如 "markdown") 。 对象 formats:传入包含 type 和其他选项的对象。

移动端抓取

设置 mobile: true 以模拟移动设备。当响应式网站在桌面端隐藏部分内容,或为移动浏览器提供不同布局时,这很有用。 对于有区域差异的网站,可结合 location 和移动端截图来验证渲染后的布局:
如果站点在设置 mobile: true 后仍然呈现桌面端布局,请通过 headers 添加移动端 User-Agent:

内容过滤

这些参数用于控制页面的哪些部分会出现在输出中。当 onlyMainContenttrue (默认值) 时,会先去掉页面框架内容 (导航、页脚等) 。includeTagsexcludeTags 是基于原始页面 DOM 而不是过滤后的结果进行匹配的,因此你的选择器应以元素在源 HTML 中的实际呈现为准。若将 onlyMainContent: false,则会使用整页 HTML 作为后续标签过滤的起点。

时间与缓存

PDF 解析

Actions

在抓取前执行浏览器 actions。这对于动态内容、页面导航或受用户访问限制的页面很有用。每个请求最多可包含 50 个 action,且所有 wait action 与 waitFor 的累计等待时间不得超过 60 秒。

actions 执行说明

  • 在使用 Write 前,需要先执行一次 click 以聚焦目标元素。
  • Scroll 可以接受一个可选的 selector,用于滚动特定元素而不是整个页面。
  • Wait 接受 milliseconds(固定延迟)或 selector(等待元素可见)两种参数中的一种。
  • actions 按顺序执行:每一步都会在下一步开始前完成。
  • actions 不支持 PDF。如果 URL 解析为 PDF 文档,请求将会失败。

高级操作示例

执行截图操作:
cURL
点击多个元素:
cURL
生成 PDF 文件:
cURL
执行 JavaScript (例如提取页面内嵌数据) :
cURL
每个 executeJavascript 操作的返回值都会记录在响应中的 actions.javascriptReturns 数组里。

完整抓取示例

以下请求组合了多个抓取选项:
cURL
该请求会返回 Markdown、HTML、原始 HTML、链接以及整页截图。它将内容范围限定为 <h1><p><a>.main-content,同时排除 #ad#footer,在开始抓取前等待 1 秒,将超时时间设置为 15 秒,并启用 PDF 解析。 有关详细信息,请参阅完整的 Scrape API 参考文档

通过 formats 提取 JSON

使用 formats 中的 JSON 格式对象,即可一次性提取结构化数据:

Agent endpoint

使用 /v2/agent 端点进行自动化的多页面数据提取。Agent 以异步方式运行:你先创建一个任务,然后通过轮询获取结果。

代理选项

检查 agent 状态

轮询 GET /v2/agent/{jobId} 以检查进度。响应中的 status 字段将为 "processing""completed""failed"
cURL
Python 和 Node SDK 还提供了一个便捷方法(firecrawl.agent()),用于启动任务并自动轮询,直到任务完成。

爬取多个页面

要爬取多个页面,请使用 /v2/crawl 端点。爬取会以异步方式运行,并返回一个任务 ID。使用 limit 参数控制爬取的页面数量。若省略该参数,爬取最多会处理 10,000 个页面。
cURL

返回结果

检查爬取任务

使用任务 ID 检查爬取状态并获取结果。
cURL
如果内容大于 10MB,或者爬取任务仍在运行中,响应中可能包含 next 参数,也就是下一页结果的 URL。

爬取 prompt 和参数预览

你可以提供自然语言 prompt,让 Firecrawl 推导爬取设置。请先预览这些设置:
cURL

爬虫选项

当使用 /v2/crawl 端点时,你可以使用以下选项自定义爬取行为。

路径过滤

起始 URL 也会与 includePaths 进行匹配。如果它不匹配任何模式,爬取结果可能会返回 0 个页面。

爬取范围

Sitemap 和去重

爬取任务的抓取选项

抓取示例

cURL
/v2/map 端点用于识别与指定网站相关的 URL。
cURL

Map 选项

其 API 参考文档见此:Map 端点文档

Firecrawl 白名单设置

允许 Firecrawl 抓取你的网站

  • User Agent(用户代理):请在防火墙或安全规则中允许 FirecrawlAgent
  • IP addresses(IP 地址):Firecrawl 不使用固定的对外 IP 地址集合。

允许你的应用调用 Firecrawl API

如果你的防火墙阻止应用向外部服务发出出站请求,你需要将 Firecrawl 的 API 服务器 IP 地址加入白名单,这样你的应用才能访问 Firecrawl API(api.firecrawl.dev):
  • IP Address: 35.245.250.27
将此 IP 添加到防火墙的出站允许列表中,这样你的后端就可以向 Firecrawl 发送抓取(scrape)、爬取(crawl)、映射(map)以及智能体(agent)请求。