クロール

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

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

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

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

from firecrawl import Firecrawlfirecrawl = 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 を使用してクロールのステータスをポーリングし、結果を取得します。

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

SDK で crawl を使う方法は 2 通りあります。

crawl メソッドはクロールの完了を待機し、完全なレスポンスを返します。ページネーションを自動処理します。ほとんどのユースケースで推奨されます。

レスポンスには、クロールのステータスと収集された全データが含まれます:

startCrawl / start_crawl メソッドは即時にクロール ID を返します。その後、ステータスを手動でポーリングして確認します。これは、長時間のクロールや独自のポーリングロジックに有用です。

最初のレスポンスではジョブ ID が返されます:

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

watcher メソッドでは、ページのクロール中にリアルタイムで更新を受け取れます。クロールを開始し、その後イベントを購読することで、データを即座に処理できます。

クロールの進行に合わせてリアルタイム通知を受け取れるよう、webhook を設定できます。これにより、クロール全体の完了を待たずに、スクレイプされたページを随時処理できます。

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

{  "success": true,  "type": "crawl.page",  "id": "crawl-job-id",  "data": [...], // 'page'イベントのページデータ  "metadata": {}, // Your custom metadata  "error": null}

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

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

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

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

• サイトマップによる検出: デフォルトでは、クローラーは URL を検出するためにウェブサイトのサイトマップを含めます (sitemap: "include") 。sitemap: "skip" を設定すると、ルート URL から HTML リンクを通じて到達できるページのみが検出されます。HTML から直接リンクされていない PDF などのアセットや、サイトマップには記載されていても深い階層にあるページは見逃されます。最大限の網羅性を得るには、デフォルト設定のままにしてください。
• クレジット使用量: クロールした各ページにつき 1 クレジットかかります。JSONモードではページごとに 4 クレジットが追加され、PDF の解析には PDF 1 ページごとに 1 クレジットかかります。
• 結果の有効期限: ジョブの結果は、完了後 24 時間は API 経由で利用できます。その後は、アクティビティログで結果を確認してください。
• クロールエラー: data 配列には、Firecrawl が正常にスクレイピングしたページが含まれます。ネットワークエラー、タイムアウト、または robots.txt によるブロックで失敗したページを取得するには、Get Crawl Errors エンドポイントを使用します。
• 外部リンク: allowExternalLinks: true を指定すると、クローラーはドメイン外を指すリンクをたどり、リンク先の各ページを 1 回スクレイピングします。ただし、その外部ページで見つかったリンクをさらにクロールすることはありません。無関係なサイト全体を取り込むことを避けるため、外部サイトのホームページ (パスのないルート URL。例: https://example.com/) へのリンクは意図的にスキップされます。これらは Get Crawl Errors にコード EXTERNAL_LINK として表示されます。リダイレクトは宛先までたどられます。これには正規 URL に解決されるリンク (たとえば http → https や www バリアント) も含まれるため、外部ホームページに到達するリダイレクトのみがスキップされます。
• 非決定的な結果: 同じ設定で実行しても、クロール結果は実行ごとに異なる場合があります。ページは並行してスクレイピングされるため、リンクが検出される順序はネットワークのタイミングや、どのページの読み込みが先に完了するかに左右されます。そのため、深さの境界付近ではサイト内の異なる分岐が異なる程度まで探索されることがあり、特に maxDiscoveryDepth の値が大きい場合に顕著です。より決定的な結果を得るには、maxConcurrency を 1 に設定するか、サイトに包括的なサイトマップがある場合は sitemap: "only" を使用してください。

Firecrawl API キーが必要な AI エージェントですか？ 自動オンボーディング手順については、firecrawl.dev/agent-onboarding/SKILL.md を参照してください。