​
安装

要安装 Firecrawl 的 Python SDK，可以使用 pip：
Python
# 使用 pip 安装 firecrawl-py

from firecrawl import Firecrawl

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

​
使用

  1. 在 firecrawl.dev 获取 API key
  2. 将该 API key 设置为名为 FIRECRAWL_API_KEY 的环境变量，或在实例化 Firecrawl 类时作为参数传入。
以下是使用 SDK 的示例：
Python
from firecrawl import Firecrawl

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

# 抓取网站：
scrape_status = firecrawl.scrape(
  'https://firecrawl.dev', 
  formats=['markdown', 'html']
)
print(scrape_status)

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

​
抓取单个 URL

要抓取单个 URL，请使用 scrape 方法。它将该 URL 作为参数并返回抓取到的文档。
Python
# Scrape a website:
scrape_result = firecrawl.scrape('firecrawl.dev', formats=['markdown', 'html'])
print(scrape_result)

​
爬取网站

要爬取网站，请使用 crawl 方法。它接收起始 URL 和可选的 options 作为参数。通过 options，你可以为爬取任务指定其他设置，例如爬取的最大页面数、允许的域名，以及输出 formats。有关自动/手动分页与限制，请参见 Pagination。
Python
job = firecrawl.crawl(url="https://docs.firecrawl.dev", limit=5, poll_interval=1, timeout=120)
print(job)

​
开始 Crawl

想要非阻塞方式？请查看下方的异步类部分。
使用 start_crawl 启动任务，无需等待。它会返回一个用于检查状态的任务 ID。需要直到完成才返回的阻塞式等待器时，请使用 crawl。分页行为与限制见分页。
Python
job = firecrawl.start_crawl(url="https://docs.firecrawl.dev", limit=10)
print(job)

​
检查爬取状态

要查看爬取任务的状态，请使用 get_crawl_status 方法。该方法接收任务 ID 作为参数，并返回该爬取任务的当前状态。
Python
status = firecrawl.get_crawl_status("<crawl-id>")
print(status)

​
取消爬取

要取消一个爬取任务，使用 cancel_crawl 方法。传入由 start_crawl 返回的任务 ID 作为参数，该方法会返回取消结果。
Python
ok = firecrawl.cancel_crawl("<crawl-id>")
print("已取消：", ok)

​
网站映射

使用 map 生成网站的 URL 列表。你可以通过选项自定义映射过程，例如排除子域或利用 sitemap。
Python
res = firecrawl.map(url="https://firecrawl.dev", limit=10)
print(res)

​
使用 WebSockets 爬取网站

要通过 WebSockets 爬取网站，先用 start_crawl 启动任务，并使用 watcher 辅助工具订阅。调用 start() 之前，使用任务 ID 创建一个 watcher，并附加处理器（例如：page、completed、failed）。
Python
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.sourceURL if doc.metadata else None)
        elif snapshot.status == "failed":
            print("错误", snapshot.status)
        else:
            print("状态", snapshot.status, snapshot.completed, "/", snapshot.total)

asyncio.run(main())
当有更多数据可用时，Firecrawl 的 crawl 和 batch 端点会返回一个 next URL。Python SDK 默认会自动分页并汇总所有文档；此时 next 为 None。你可以禁用自动分页或设置上限。

​
爬取

使用 waiter 方法 crawl 可获得最简便的体验，或者启动一个作业并手动翻页。
简单抓取（自动分页，默认）
手动爬取并控制分页（单页）
  • 先启动任务，然后将 auto_paginate=False，按页逐次获取。
Python
crawl_job = client.start_crawl("https://example.com", limit=100)

status = client.get_crawl_status(crawl_job.id, pagination_config=PaginationConfig(auto_paginate=False))
print("抓取单页：", status.status, "文档数：", len(status.data), "下一页：", status.next)
手动抓取并设定限制（自动分页 + 提前停止）
  • 保持自动分页开启，但可通过 max_pages、max_results 或 max_wait_time 提前停止。
Python
status = client.get_crawl_status(
    crawl_job.id,
    pagination_config=PaginationConfig(max_pages=2, max_results=50, max_wait_time=15),
)
print("爬取受限：", status.status, "文档数：", len(status.data), "下一页：", status.next)

​
批量抓取

使用 waiter 方法 batch_scrape，或启动任务后手动分页处理。
简单批量爬取（自动分页，默认）
手动批量抓取并控制分页（单页）
  • 先启动作业，然后将 auto_paginate=False，一次获取一页。
Python
batch_job = client.start_batch_scrape(urls)
status = client.get_batch_scrape_status(batch_job.id, pagination_config=PaginationConfig(auto_paginate=False))
print("批处理单页：", status.status, "文档数：", len(status.data), "下一页：", status.next)
受限的手动批量抓取（自动分页 + 提前停止）
  • 保持自动分页开启，但可通过 max_pages、max_results 或 max_wait_time 提前停止。
Python
status = client.get_batch_scrape_status(
    batch_job.id,
    pagination_config=PaginationConfig(max_pages=2, max_results=100, max_wait_time=20),
)
print("批处理受限：", status.status, "文档数：", len(status.data), "下一页：", status.next)

​
错误处理

SDK 会处理 Firecrawl API 返回的错误并抛出相应异常。如果在请求过程中发生错误，将抛出包含详细错误信息的异常。

​
异步类

进行异步操作时，请使用 AsyncFirecrawl 类。其方法与 Firecrawl 一致，但不会阻塞主线程。
Python
import asyncio
from firecrawl import AsyncFirecrawl

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

    # 抓取
    doc = await firecrawl.scrape("https://firecrawl.dev", formats=["markdown"])  # type: ignore[arg-type]
    print(doc.get("markdown"))

    # 搜索
    results = await firecrawl.search("firecrawl", limit=2)
    print(results.get("web", []))

    # 爬取（启动与状态）
    started = await firecrawl.start_crawl("https://docs.firecrawl.dev", limit=3)
    status = await firecrawl.get_crawl_status(started.id)
    print(status.status)

    # 批量抓取（等待完成）
    job = await firecrawl.batch_scrape([
        "https://firecrawl.dev",
        "https://docs.firecrawl.dev",
    ], formats=["markdown"], poll_interval=1, timeout=60)
    print(job.status, job.completed, job.total)

asyncio.run(main())