爬取 | Firecrawl

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

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

在 Playground 中试用

在交互式 Playground 中测试爬取功能——无需代码。

安装

# 使用 pip 安装 firecrawl-py

from firecrawl import Firecrawl

firecrawl = Firecrawl(
  # 无需 API 密钥即可开始使用 — 添加一个以获得更高的限流额度：
  # api_key="fc-YOUR-API-KEY",
)

// 使用 npm 安装 firecrawl

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({
  // 无需 API 密钥即可开始使用 — 添加一个以获得更高的限流额度：
  // apiKey: "fc-YOUR-API-KEY",
});

# 使用 npm 全局安装
npm install -g firecrawl

# 身份验证(一次性设置)
firecrawl login

基本用法

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

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-你的API密钥")

docs = firecrawl.crawl(url="https://docs.firecrawl.dev", limit=10)
print(docs)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-你的API密钥" });

const docs = await firecrawl.crawl('https://docs.firecrawl.dev', { limit: 10 });
console.log(docs);

curl -s -X POST "https://api.firecrawl.dev/v2/crawl" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.firecrawl.dev",
    "limit": 10
  }'

# 启动爬取任务(返回任务 ID)
firecrawl crawl https://firecrawl.dev

# 等待完成并显示进度
firecrawl crawl https://firecrawl.dev --wait --progress --limit 100

每爬取 1 个页面会消耗 1 个额度。爬取的默认 limit 为 10,000 个页面。在开始之前，爬取端点会检查你的剩余额度是否足以覆盖 limit；如果不足，则会返回 402 (需要付款) 错误。你可以设置更低的 limit 来匹配计划的爬取规模 (例如将 limit 设为 100) ，以避免这种情况。某些选项会额外消耗额度：JSON 模式每个页面额外消耗 4 个额度，增强代理每个页面额外消耗 4 个额度，PDF 解析每个 PDF 页面额外消耗 1 个额度。

Scrape 选项

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

from firecrawl import Firecrawl

firecrawl = 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
    }
)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });

// 使用 scrape 选项进行爬取
const crawlResponse = await firecrawl.crawl('https://example.com', {
  limit: 100,
  scrapeOptions: {
    formats: [
      'markdown',
      {
        type: 'json',
        schema: { type: 'object', properties: { title: { type: 'string' } } },
      },
    ],
    proxy: 'auto',
    maxAge: 600000,
    onlyMainContent: true,
  },
});

检查爬取状态

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

status = firecrawl.get_crawl_status("<crawl-id>")
print(status)

const status = await firecrawl.getCrawlStatus("<crawl-id>");
console.log(status);

# 启动爬取后，使用 jobId 轮询状态
curl -s -X GET "https://api.firecrawl.dev/v2/crawl/<jobId>" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

# 使用作业 ID 检查爬取状态
firecrawl crawl <job-id>

任务结果在完成后 24 小时内可通过 API 获取。此后，你仍可以在活动日志中查看你的爬取历史和结果。

爬取结果中的 data 数组里包含的是 Firecrawl 成功抓取的页面，即使目标站点返回了 404 等 HTTP 错误。metadata.statusCode 字段显示的是目标站点返回的 HTTP 状态码。若要获取 Firecrawl 本身未能成功抓取的页面 (例如网络错误、超时或被 robots.txt 拦截) ，请使用专门的 Get Crawl Errors 端点 (GET /crawl/{id}/errors) 。

响应处理

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

仅在直接调用 API 时，skip 和 next 参数才生效。如果你使用 SDK，我们会代为处理，并一次性返回全部结果。

{
  "status": "抓取中",
  "total": 36,
  "completed": 10,
  "creditsUsed": 10,
  "expiresAt": "2024-00-00T00:00:00.000Z",
  "next": "https://api.firecrawl.dev/v2/crawl/123-456-789?skip=10",
  "data": [
    {
      "markdown": "[Firecrawl 文档首页![浅色标志](https://mintlify.s3-us-west-1.amazonaws.com/firecrawl/logo/light.svg)!...",
      "html": "<!DOCTYPE html><html lang=\"en\" class=\"js-focus-visible lg:[--scroll-mt:9.5rem]\" data-js-focus-visible=\"\">...",
      "metadata": {
        "title": "使用 Groq Llama 3 构建“网站聊天” | Firecrawl",
        "language": "en",
        "sourceURL": "https://docs.firecrawl.dev/learn/rag-llama3",
        "description": "了解如何使用 Firecrawl、Groq Llama 3 和 Langchain 构建一个“网站聊天”机器人。",
        "ogLocaleAlternate": [],
        "statusCode": 200
      }
    },
    ...
  ]
}

{
  "status": "completed",
  "total": 36,
  "completed": 36,
  "creditsUsed": 36,
  "expiresAt": "2024-00-00T00:00:00.000Z",
  "next": "https://api.firecrawl.dev/v2/crawl/123-456-789?skip=26",
  "data": [
    {
      "markdown": "[Firecrawl 文档首页![浅色 logo](https://mintlify.s3-us-west-1.amazonaws.com/firecrawl/logo/light.svg)!...",
      "html": "<!DOCTYPE html><html lang=\"en\" class=\"js-focus-visible lg:[--scroll-mt:9.5rem]\" data-js-focus-visible=\"\">...",
      "metadata": {
        "title": "使用 Groq Llama 3 构建“网站聊天” | Firecrawl",
        "language": "en",
        "sourceURL": "https://docs.firecrawl.dev/learn/rag-llama3",
        "description": "了解如何使用 Firecrawl、Groq Llama 3 和 LangChain 构建一个“网站聊天”机器人。",
        "ogLocaleAlternate": [],
        "statusCode": 200
      }
    },
    ...
  ]
}

SDK 方法

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

抓取并等待

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

from firecrawl import Firecrawl
from firecrawl.types import ScrapeOptions

firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")

# 爬取网站：
crawl_status = firecrawl.crawl(
  'https://firecrawl.dev', 
  limit=100, 
  scrape_options=ScrapeOptions(formats=['markdown', 'html']),
  poll_interval=30
)
print(crawl_status)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({apiKey: "fc-YOUR_API_KEY"});

const crawlResponse = await firecrawl.crawl('https://firecrawl.dev', {
  limit: 100,
  scrapeOptions: {
    formats: ['markdown', 'html'],
  }
})

console.log(crawlResponse)

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

success=True
status='completed'
completed=100
total=100
creditsUsed=100
expiresAt=datetime.datetime(2025, 4, 23, 19, 21, 17, tzinfo=TzInfo(UTC))
next=None
data=[
  Document(
    markdown='[第 7 天 - 发布周 III · 集成日（4 月 14 日至 20 日）](...',
    metadata={
      'title': '15 个 Python 网页爬取项目：从入门到进阶',
      ...
      'scrapeId': '97dcf796-c09b-43c9-b4f7-868a7a5af722',
      'sourceURL': 'https://www.firecrawl.dev/blog/python-web-scraping-projects',
      'url': 'https://www.firecrawl.dev/blog/python-web-scraping-projects',
      'statusCode': 200
    }
  ),
  ...
]

{
  success: true,
  status: "completed",
  completed: 100,
  total: 100,
  creditsUsed: 100,
  expiresAt: "2025-04-23T19:28:45.000Z",
  data: [
    {
      markdown: "[Day 7 - Launch Week III.Integrations DayApril ...",
      html: `<!DOCTYPE html><html lang="en" class="light" style="color...`,
      metadata: [Object],
    },
    ...
  ]
}

启动后稍后检查

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

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

job = firecrawl.start_crawl(url="https://docs.firecrawl.dev", limit=10)
print(job)

# 检查爬取任务的状态
status = firecrawl.get_crawl_status(job.id)
print(status)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const { id } = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 10 });
console.log(id);

// 检查抓取进度
const status = await firecrawl.getCrawlStatus(id);
console.log(status);

curl -s -X POST "https://api.firecrawl.dev/v2/crawl" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.firecrawl.dev",
    "limit": 10
  }'

# 启动爬取(异步,立即返回作业 ID)
firecrawl crawl https://firecrawl.dev --limit 100

# 稍后检查状态
firecrawl crawl <job-id>

初始响应会返回任务 ID：

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

使用 WebSocket 获取实时结果

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

import asyncio
from firecrawl import AsyncFirecrawl

async def main():
    firecrawl = AsyncFirecrawl(api_key="fc-YOUR-API-KEY")

    # 首先启动爬取
    started = await firecrawl.start_crawl("https://firecrawl.dev", limit=5)

    # 监听更新（快照）直到终止状态
    async for snapshot in firecrawl.watcher(started.id, kind="crawl", poll_interval=2, timeout=120):
        if snapshot.status == "completed":
            print("完成", snapshot.status)
            for doc in snapshot.data:
                print("文档", doc.metadata.source_url if doc.metadata else None)
        elif snapshot.status == "failed":
            print("错误", snapshot.status)
        else:
            print("状态", snapshot.status, snapshot.completed, "/", snapshot.total)

asyncio.run(main())

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR-API-KEY' });

// 启动一次爬取并开始监控
const { id } = await firecrawl.startCrawl('https://mendable.ai', {
  excludePaths: ['blog/*'],
  limit: 5,
});

const watcher = firecrawl.watcher(id, { kind: 'crawl', pollInterval: 2, timeout: 120 });

watcher.on('document', (doc) => {
  console.log('DOC', doc);
});

watcher.on('error', (err) => {
  console.error('ERR', err?.error || err);
});

watcher.on('done', (state) => {
  console.log('DONE', state.status);
});

// 开始监控（优先使用 WS，回退到 HTTP）
await watcher.start();

Webhooks

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

cURL

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

事件类型

事件	描述
`crawl.started`	在爬取开始时触发
`crawl.page`	每个页面成功抓取后触发
`crawl.completed`	在爬取结束时触发
`crawl.failed`	爬取过程中发生错误时触发

负载

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

验证 webhook 签名

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

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

在验证签名之前，切勿处理任何 webhook。X-Firecrawl-Signature 请求头中的签名格式为：sha256=abc123def456...

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

配置参考

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

参数	类型	默认值	说明
`url`	`string`	(必填)	开始爬取的起始 URL
`limit`	`integer`	`10000`	最大爬取页面数
`maxDiscoveryDepth`	`integer`	(无)	基于链接发现跳数、相对于根 URL 的最大深度，而不是 URL 中 `/` 分段的数量。每当在某个页面上发现一个新 URL 时，其深度都会被设为比发现它的页面高 1。根站点和通过站点地图发现的页面，其发现深度为 0。处于最大深度的页面仍会被抓取，但不会继续跟踪其上的链接。
`includePaths`	`string[]`	(无)	要包含的 URL 路径正则表达式模式。仅爬取匹配的路径。
`excludePaths`	`string[]`	(无)	要从爬取中排除的 URL 路径正则表达式模式
`regexOnFullURL`	`boolean`	`false`	让 `includePaths`/`excludePaths` 针对完整 URL (包括查询参数) 进行匹配，而不只是路径部分
`crawlEntireDomain`	`boolean`	`false`	跟踪指向同级或上级 URL 的站内链接，而不只是子路径
`allowSubdomains`	`boolean`	`false`	跟踪指向主域名下子域名的链接
`allowExternalLinks`	`boolean`	`false`	跟踪指向外部网站的链接
`sitemap`	`string`	`"include"`	站点地图处理方式：`"include"` (默认) 、`"skip"` 或 `"only"`
`ignoreQueryParameters`	`boolean`	`false`	避免因查询参数不同而对同一路径重复抓取
`ignoreRobotsTxt`	`boolean`	`false`	忽略网站的 robots.txt 规则。仅限 Enterprise — 请联系 support@firecrawl.com 启用。
`robotsUserAgent`	`string`	(无)	用于评估 robots.txt 的自定义 User-Agent 字符串。设置后，将使用此 User-Agent 获取 robots.txt，并根据它而不是默认值来匹配规则。仅限 Enterprise — 请联系 support@firecrawl.com 启用。
`delay`	`number`	(无)	每次抓取之间的延迟时间 (秒) ，以遵守速率限制。设置此项会强制并发数为 1。
`maxConcurrency`	`integer`	(无)	最大并发抓取数。默认使用你团队的并发限制。
`scrapeOptions`	`object`	(无)	应用于每个抓取页面的选项 (formats、代理、缓存、actions 等)
`webhook`	`object`	(无)	用于实时通知的 webhook 配置
`prompt`	`string`	(无)	用于生成爬取选项的自然语言提示。显式设置的参数会覆盖自动生成的对应参数。

重要说明

默认情况下，crawl 会忽略不属于你提供的 URL 子路径的链接。例如，如果你抓取 website.com/blogs/，则不会返回 website.com/other-parent/blog-1。使用 crawlEntireDomain 参数可包含同级路径和父级路径。要在抓取 website.com 时一并抓取 blog.website.com 这类子域名，请使用 allowSubdomains 参数。

站点地图发现：默认情况下，爬虫会包含网站的站点地图来发现 URL (sitemap: "include") 。如果设置 sitemap: "skip"，则只会发现可通过根 URL 的 HTML 链接访问到的页面。像 PDF 这类资源，或列在站点地图中但未在 HTML 中直接链接的深层页面，都会被遗漏。为了获得最大覆盖率，建议保留默认设置。
Credit 消耗：每抓取一个页面消耗 1 个 credit。JSON 模式每页额外消耗 4 个 credit，增强代理每页额外消耗 4 个 credit，PDF 解析则每个 PDF 页面消耗 1 个 credit。
结果过期时间：任务结果在完成后的 24 小时内可通过 API 获取。此后，请在活动日志中查看结果。
抓取错误：data 数组包含 Firecrawl 成功抓取的页面。使用 Get Crawl Errors 端点可获取因网络错误、超时或被 robots.txt 阻止而失败的页面。
非确定性结果：同一配置在多次运行之间的抓取结果可能会有所不同。页面会并发抓取，因此链接被发现的顺序取决于网络时序以及哪些页面先完成加载。这意味着在接近深度边界时，站点的不同分支可能会被探索到不同程度，尤其是在 maxDiscoveryDepth 值较高时。要获得更稳定的结果，请将 maxConcurrency 设置为 1，或者在站点拥有完整站点地图时使用 sitemap: "only"。

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

快速上手

核心端点

更多

快速入门

开发者指南

Webhooks

使用场景

其他

参与贡献

爬取

在 Playground 中试用

安装

基本用法

Scrape 选项

检查爬取状态

响应处理

SDK 方法

抓取并等待

启动后稍后检查

使用 WebSocket 获取实时结果

Webhooks

事件类型

负载

验证 webhook 签名

配置参考

重要说明

在 Playground 中试用

​安装

​基本用法

​Scrape 选项

​检查爬取状态

​响应处理

​SDK 方法

​抓取并等待

​启动后稍后检查

​使用 WebSocket 获取实时结果

​Webhooks

​事件类型

​负载

​验证 webhook 签名

​配置参考

​重要说明

安装

基本用法

Scrape 选项

检查爬取状态

响应处理

SDK 方法

抓取并等待

启动后稍后检查

使用 WebSocket 获取实时结果

Webhooks

事件类型

负载

验证 webhook 签名

配置参考

重要说明