跳转到主要内容
爬取会将一个 URL 提交给 Firecrawl，并递归发现和抓取所有可到达的子页面。它会自动处理 sitemap、JavaScript 渲染和速率限制，并为每个页面返回干净的 Markdown 或结构化数据。
  • 通过 sitemap 和递归链接遍历发现页面
  • 支持路径过滤、深度限制以及对子域名/外部链接的控制
  • 通过轮询、WebSocket 或 webhook 返回结果

在 Playground 中试用

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

​
安装

# 使用 pip 安装 firecrawl-py

from firecrawl import Firecrawl

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

​
基本用法

调用 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)
每抓取 1 个页面会消耗 1 个积分。抓取的默认 limit 为 10,000 个页面，你可以设置更低的 limit 来控制积分消耗 (例如将 limit 设为 100) 。某些选项会额外消耗积分：JSON 模式每个页面额外消耗 4 个积分，增强代理每个页面额外消耗 4 个积分，PDF 解析每个 PDF 页面额外消耗 1 个积分。

​
Scrape 选项

Scrape 端点的所有选项都可通过 scrapeOptions (JS) / scrape_options (Python) 在 crawl 中使用。它们将应用于爬虫抓取的每个页面，包括 formats、proxy、caching、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
    }
)

​
检查爬取状态

使用任务 ID 轮询爬取状态并获取结果。 
status = firecrawl.get_crawl_status("<crawl-id>")
print(status)
任务结果在完成后 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
      }
    },
    ...
  ]
}

​
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)
响应包括爬取状态及所有抓取到的数据： 
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
    }
  ),
  ...
]

​
启动后稍后检查

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)
初始响应会返回任务 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())

​
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 为真实请求且未被篡改。
  1. 在账户设置中的 Advanced (高级) 选项卡 获取你的 webhook 密钥 (secret)
  2. 从 X-Firecrawl-Signature 请求头中提取签名
  3. 使用该密钥对原始请求体计算 HMAC-SHA256
  4. 使用时间安全函数 (timing-safe function) 将计算结果与签名请求头中的值进行比较
在验证签名之前，切勿处理任何 webhook。X-Firecrawl-Signature 请求头中的签名格式为：sha256=abc123def456...
有关 JavaScript 和 Python 的完整实现示例，请参阅 Webhook 安全文档。如需查看更全面的 webhook 文档，包括详细的事件负载、负载结构、高级配置和故障排查，请参阅 Webhooks 文档。

​
配置参考

提交 crawl 任务时可用的完整参数集：
参数类型默认值说明
urlstring(必填)开始爬取的起始 URL
limitinteger10000最大爬取页面数
maxDiscoveryDepthinteger(无)基于链接发现跳数、相对于根 URL 的最大深度，而不是 URL 中 / 分段的数量。每当在某个页面上发现一个新 URL 时，其深度都会被设为比发现它的页面高 1。根站点和通过站点地图发现的页面，其发现深度为 0。处于最大深度的页面仍会被抓取，但不会继续跟踪其上的链接。
includePathsstring[](无)要包含的 URL 路径正则表达式模式。仅爬取匹配的路径。
excludePathsstring[](无)要从爬取中排除的 URL 路径正则表达式模式
regexOnFullURLbooleanfalse让 includePaths/excludePaths 针对完整 URL (包括查询参数) 进行匹配，而不只是路径部分
crawlEntireDomainbooleanfalse跟踪指向同级或上级 URL 的站内链接，而不只是子路径
allowSubdomainsbooleanfalse跟踪指向主域名下子域名的链接
allowExternalLinksbooleanfalse跟踪指向外部网站的链接
sitemapstring"include"站点地图处理方式："include" (默认) 、"skip" 或 "only"
ignoreQueryParametersbooleanfalse避免因查询参数不同而对同一路径重复抓取
delaynumber(无)每次抓取之间的延迟时间 (秒) ，以遵守速率限制
maxConcurrencyinteger(无)最大并发抓取数。默认使用你团队的并发限制。
scrapeOptionsobject(无)应用于每个抓取页面的选项 (formats、代理、缓存、actions 等)
webhookobject(无)用于实时通知的 webhook 配置
promptstring(无)用于生成爬取选项的自然语言提示。显式设置的参数会覆盖自动生成的对应参数。

​
重要说明

默认情况下，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"。