​
インストール

Firecrawl の Python SDK をインストールするには、pip を使用します：
Python
# pip install firecrawl-py

from firecrawl import Firecrawl

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

​
使い方

  1. firecrawl.dev で API キーを取得します
  2. API キーを環境変数 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と任意のオプションを引数に取ります。オプションでは、クロールするページ数の上限、許可するドメイン、出力フォーマットなど、クロールジョブの追加設定を指定できます。自動/手動のページネーションや制限については Pagination を参照してください。
Python
job = firecrawl.crawl(url="https://docs.firecrawl.dev", limit=5, poll_interval=1, timeout=120)
print(job)

​
クロールを開始

ノンブロッキングがお好みですか？下のAsync Classセクションをご覧ください。
start_crawl を使うと待たずにジョブを開始できます。ステータス確認に使えるジョブの ID を返します。完了までブロックして待機したい場合は crawl を使用してください。ページングの動作と制限は Pagination を参照してください。
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 の一覧を生成します。オプションで、サブドメインの除外やサイトマップの利用など、マッピングの挙動をカスタマイズできます。
Python
res = firecrawl.map(url="https://firecrawl.dev", limit=10)
print(res)

​
WebSockets を使ったウェブサイトのクロール

WebSockets でウェブサイトをクロールするには、start_crawl でジョブを開始し、watcher ヘルパーで購読します。ジョブ ID を指定して watcher を作成し、start() を呼び出す前にハンドラー（例: 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", 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 になります。自動ページネーションを無効化したり、上限を設定することも可能です。

​
クロール

最も手軽なのはウェイター方式の crawl を使うことです。もしくはジョブを開始して手動でページ処理を行ってください。
シンプルなクロール（自動ページネーション、デフォルト）
ページネーションを手動制御するクロール（単一ページ）
  • ジョブを開始し、auto_paginate=False を指定して1ページずつ取得します。
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 を使うか、ジョブを開始して手動でページングします。
シンプルなバッチスクレイプ（自動ページネーション、デフォルト）
  • 既定のフローは Batch Scrape を参照してください。
ページネーション制御付きの手動バッチスクレイプ（単一ページ）
  • ジョブを開始し、auto_paginate=False を指定して1ページずつ取得します。
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())