クロール

Crawl は URL を Firecrawl に送信し、到達可能なすべてのサブページを再帰的に検出してスクレイピングします。サイトマップ、JavaScript レンダリング、レート制限を自動的に処理し、各ページについてクリーンな Markdown または構造化データを返します。

サイトマップとリンクの再帰的なたどりによってページを検出
パスのフィルタリング、深さ制限、サブドメインや外部リンクの制御をサポート
ポーリング、WebSocket、または Webhook で結果を返す

Playground で試す

インタラクティブな Playground でクロールをテストできます。コードは不要です。

インストール

# pip install firecrawl-py

from firecrawl import Firecrawl

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

基本的な使い方

開始 URL を指定して POST /v2/crawl を呼び出し、クロールジョブを送信します。このエンドポイントは、結果をポーリングするために使用するジョブ ID を返します。

from firecrawl import Firecrawl

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

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

クロールされたページ 1 件ごとに 1 クレジットを消費します。デフォルトのクロール limit は 10,000 ページです。クレジット消費を抑えるには、limit: 100 のように、クロール対象を 100 ページに制限するなど、より小さい limit を設定してください。特定のオプションには追加クレジットが必要です。JSONモードはページごとに追加で 4 クレジット、拡張プロキシはページごとに追加で 4 クレジット、PDF 解析は PDF のページごとに 1 クレジットを消費します。

スクレイプオプション

Scrape エンドポイントのすべてのオプションは、scrapeOptions (JS) / scrape_options (Python) 経由で crawl でも利用できます。これらはクローラーがスクレイプするすべてのページに適用されます (フォーマット、プロキシ、キャッシュ、アクション、ロケーション、タグを含む) 。

from firecrawl import Firecrawl

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

# スクレイプオプション付きでクロール
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 経由で取得できます。この期間を過ぎても、activity logs からクロール履歴と結果を参照できます。

クロール結果の data 配列に含まれているページは、対象サイトが 404 のような HTTP エラーを返した場合でも、Firecrawl がスクレイピングに成功したページです。metadata.statusCode フィールドには、対象サイトから返された HTTP ステータスコードが含まれます。Firecrawl 自体がスクレイピングに失敗したページ (ネットワークエラー、タイムアウト、robots.txt によるブロックなど) を取得するには、専用の Get Crawl Errors エンドポイント (GET /crawl/{id}/errors) を使用してください。

レスポンスの処理

レスポンスはクロールのステータスによって異なります。未完了のレスポンス、またはサイズが10MBを超える大きなレスポンスの場合は、next URLパラメータが付与されます。次の10MBのデータを取得するには、このURLにリクエストしてください。next パラメータがない場合は、クロールデータの終端を示します。

skip と next のパラメータが関係するのは、API を直接呼び出す場合のみです。 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 を使う方法は 2 通りあります。

クロールして待つ

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日目 - Launch Week III・Integrations Day（4月14日〜20日）](...',
    metadata={
      'title': 'Pythonのウェブスクレイピングプロジェクト15選：初級から上級まで',
      ...
      '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", 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"]
      }
    }'

イベントタイプ

Event	Description
`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 リクエストには、HMAC-SHA256 シグネチャを含む X-Firecrawl-Signature ヘッダーが含まれます。Webhook が正当で改ざんされていないことを確認するために、必ずこのシグネチャを検証してください。

アカウント設定の Advanced タブから webhook secret を取得する
X-Firecrawl-Signature ヘッダーからシグネチャを取得する
取得した secret を使い、生のリクエストボディに対して HMAC-SHA256 を計算する
タイミング攻撃耐性のある関数を使って、計算結果とヘッダーのシグネチャを比較する

シグネチャを最初に検証せずに webhook を処理してはいけません。X-Firecrawl-Signature ヘッダーには、sha256=abc123def456... という形式でシグネチャが含まれています。

JavaScript と Python による完全な実装例については、Webhook セキュリティのドキュメントを参照してください。詳細なイベントペイロード、ペイロード構造、高度な設定、トラブルシューティングを含む包括的な webhook ドキュメントについては、Webhooks ドキュメントを参照してください。

設定リファレンス

クロールジョブの送信時に指定できる全パラメータ:

Parameter	Type	Default	Description
`url`	`string`	(required)	クロール開始元の URL
`limit`	`integer`	`10000`	クロールするページの最大数
`maxDiscoveryDepth`	`integer`	(none)	URL 内の `/` セグメント数ではなく、リンクの発見ホップ数に基づくルート URL からの最大深度。ページ上で新しい URL が見つかるたびに、その URL には発見元のページより 1 つ深い深度が割り当てられます。ルートサイトおよびサイトマップに含まれるページの発見深度は 0 です。最大深度のページもスクレイプされますが、そのページ上のリンクはたどりません。
`includePaths`	`string[]`	(none)	含める URL パスの正規表現パターン。一致するパスのみをクロールします。
`excludePaths`	`string[]`	(none)	クロール対象から除外する URL パスの正規表現パターン
`regexOnFullURL`	`boolean`	`false`	`includePaths`/`excludePaths` を、パスのみではなく完全な URL (クエリパラメータを含む) に対して照合します
`crawlEntireDomain`	`boolean`	`false`	子パスだけでなく、同一ドメイン内の兄弟 URL や親 URL への内部リンクもたどります
`allowSubdomains`	`boolean`	`false`	メインドメインのサブドメインへのリンクもたどります
`allowExternalLinks`	`boolean`	`false`	外部サイトへのリンクもたどります
`sitemap`	`string`	`"include"`	サイトマップの扱い: `"include"` (デフォルト) 、`"skip"`、または `"only"`
`ignoreQueryParameters`	`boolean`	`false`	クエリパラメータが異なっていても、同じパスの再スクレイピングを避けます
`delay`	`number`	(none)	レート制限を順守するためのスクレイプ間の遅延 (秒)
`maxConcurrency`	`integer`	(none)	同時スクレイプの最大数。デフォルトでは、チームの同時実行数上限が使用されます。
`scrapeOptions`	`object`	(none)	すべてのスクレイプ対象ページに適用されるオプション (フォーマット、プロキシ、キャッシュ、アクションなど)
`webhook`	`object`	(none)	リアルタイム通知用の Webhook 設定
`prompt`	`string`	(none)	クロールオプションを生成するための自然言語プロンプト。明示的に設定したパラメータは、生成された対応項目より優先されます。

重要な詳細

デフォルトでは、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 リンクを通じて到達できるページのみが検出されます。HTML から直接リンクされていない PDF などのアセットや、サイトマップには記載されていても深い階層にあるページは見逃されます。最大限の網羅性を得るには、デフォルト設定のままにしてください。
クレジット使用量: クロールした各ページにつき 1 クレジットかかります。JSONモードではページごとに 4 クレジット、enhanced proxy ではページごとに 4 クレジットが追加され、PDF の解析には PDF 1 ページごとに 1 クレジットかかります。
結果の有効期限: ジョブの結果は、完了後 24 時間は API 経由で利用できます。その後は、アクティビティログで結果を確認してください。
クロールエラー: data 配列には、Firecrawl が正常にスクレイピングしたページが含まれます。ネットワークエラー、タイムアウト、または robots.txt によるブロックで失敗したページを取得するには、Get Crawl Errors エンドポイントを使用します。
非決定的な結果: 同じ設定で実行しても、クロール結果は実行ごとに異なる場合があります。ページは並行してスクレイピングされるため、リンクが検出される順序はネットワークのタイミングや、どのページの読み込みが先に完了するかに左右されます。そのため、深さの境界付近ではサイト内の異なる分岐が異なる程度まで探索されることがあり、特に maxDiscoveryDepth の値が大きい場合に顕著です。より決定的な結果を得るには、maxConcurrency を 1 に設定するか、サイトに包括的なサイトマップがある場合は sitemap: "only" を使用してください。

はじめに

新機能

コア機能

開発者向けガイド

ウェブフック

ユースケース

貢献方法

Playground で試す

インストール

基本的な使い方

スクレイプオプション

クロールステータスの確認

レスポンスの処理

SDK メソッド

クロールして待つ

開始して後で確認

WebSocket によるリアルタイム結果

Webhooks

イベントタイプ

ペイロード

Webhook シグネチャの検証

設定リファレンス

重要な詳細

はじめに

新機能

コア機能

開発者向けガイド

ウェブフック

ユースケース

貢献方法

Playground で試す

​インストール

​基本的な使い方

​スクレイプオプション

​クロールステータスの確認

​レスポンスの処理

​SDK メソッド

​クロールして待つ

​開始して後で確認

​WebSocket によるリアルタイム結果

​Webhooks

​イベントタイプ

​ペイロード

​Webhook シグネチャの検証

​設定リファレンス

​重要な詳細

インストール

基本的な使い方

スクレイプオプション

クロールステータスの確認

レスポンスの処理

SDK メソッド

クロールして待つ

開始して後で確認

WebSocket によるリアルタイム結果

Webhooks

イベントタイプ

ペイロード

Webhook シグネチャの検証

設定リファレンス

重要な詳細