バッチスクレイピング

バッチスクレイピングでは、1つのジョブで複数のURLをスクレイピングできます。URLのリストと任意のパラメータを渡すと、Firecrawl がそれらを並行して処理し、すべての結果をまとめて返します。

明示的に指定したURLのリストを対象とする点を除き、/crawl と同様に動作します
同期モードと非同期モードに対応
構造化抽出を含む、すべてのスクレイピングオプションをサポート
ジョブごとに同時実行数を設定可能

オペレーション#

タスク	APIリファレンス	SDKでの呼び方
バッチを開始	`batch-scrape`	`batchScrape` / `batch_scrape`, `startBatchScrape` / `start_batch_scrape`
ステータスと結果を確認	`batch-scrape-get`	`getBatchScrapeStatus` / `get_batch_scrape_status`
実行中のバッチをキャンセル	`batch-scrape-delete`	IDを指定してバッチジョブをキャンセルまたは削除
Errorsを確認	`batch-scrape-get-errors`	失敗したURL向けのエラー／ステータス確認ヘルパー

仕組み#

バッチスクレイプは、次の2つの方法で実行できます。

モード	SDK メソッド (JS / Python)	動作
同期	`batchScrape` / `batch_scrape`	バッチを開始し、完了まで待機して、すべての結果を返します
非同期	`startBatchScrape` / `start_batch_scrape`	バッチを開始し、ポーリングまたは Webhook 用のジョブ ID を返します

基本的な使い方#

レスポンス#

batchScrape / batch_scrape を呼び出すと、バッチ完了時に完全な結果が返されます。

完了

{  "status": "completed",  "total": 36,  "completed": 36,  "creditsUsed": 36,  "expiresAt": "2024-00-00T00:00:00.000Z",  "next": "https://api.firecrawl.dev/v2/batch/scrape/123-456-789?skip=26",  "data": [    {      "markdown": "[Firecrawl Docs のホームページ![light logo](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      }    },    ...  ]}

startBatchScrape / start_batch_scrape を呼び出すと、getBatchScrapeStatus / get_batch_scrape_status、API エンドポイント /batch/scrape/{id}、または Webhook を使って追跡できるジョブ ID が返されます。ジョブの結果は、完了後 24 時間まで API 経由で取得できます。この期間を過ぎても、activity logs からバッチスクレイプの履歴と結果を確認できます。

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

並行実行数#

デフォルトでは、バッチスクレイプジョブはチームのブラウザ同時実行数の上限をフルに使用します (Rate Limits を参照) 。maxConcurrency パラメータでジョブごとにこの上限を下げることができます。

たとえば、maxConcurrency: 50 とすると、そのジョブは同時に 50 件までしかスクレイプを実行しません。大規模なバッチでこの値を低くしすぎると処理が大幅に遅くなるため、他のジョブ用に同時実行枠を残す必要がある場合にのみ減らしてください。

構造化抽出#

バッチスクレイプを使用して、バッチ内のすべてのページから構造化データを抽出できます。これは、URLのリストに同じスキーマを適用したい場合に便利です。

レスポンス#

batchScrape / batch_scrape は完全な結果を返します：

完了

{  "status": "completed",  "total": 36,  "completed": 36,  "creditsUsed": 36,  "expiresAt": "2024-00-00T00:00:00.000Z",  "next": "https://api.firecrawl.dev/v2/batch/scrape/123-456-789?skip=26",  "data": [    {      "json": {        "title": "Build a 'Chat with website' using Groq Llama 3 | Firecrawl",        "description": "Firecrawl、Groq Llama 3、LangChain を使って「自分のウェブサイトとチャットできる」ボットの作り方を解説します。"      }    },    ...  ]}

startBatchScrape / start_batch_scrape はジョブ ID を返します：

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

Webhooks#

バッチ内の各 URL がスクレイプされるたびにリアルタイムで通知を受け取れるよう、webhook を設定できます。これにより、バッチ全体の完了を待たずに結果を即時に処理できます。

cURL

curl -X POST https://api.firecrawl.dev/v2/batch/scrape \    -H 'Content-Type: application/json' \    -H 'Authorization: Bearer YOUR_API_KEY' \    -d '{      "urls": [        "https://example.com/page1",        "https://example.com/page2",        "https://example.com/page3"      ],      "webhook": {        "url": "https://your-domain.com/webhook",        "metadata": {          "any_key": "any_value"        },        "events": ["started", "page", "completed"]      }    }'

イベントの種類#

イベント	説明
`batch_scrape.started`	バッチスクレイプジョブが開始されました
`batch_scrape.page`	1件のURLのスクレイプに成功しました
`batch_scrape.completed`	すべてのURLの処理が完了しました
`batch_scrape.failed`	バッチスクレイプジョブでエラーが発生しました

ペイロード#

各Webhook配信には、次の構造のJSONボディが含まれます:

{  "success": true,  "type": "batch_scrape.page",  "id": "batch-job-id",  "data": [...],  "metadata": {},  "error": null}

Webhook シグネチャの検証#

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

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

Warning

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

JavaScript と Python による実装の完全な例については、Webhook セキュリティのドキュメントを参照してください。

詳細なイベントペイロード、高度な設定、トラブルシューティングなどを含む webhook の包括的なドキュメントについては、Webhooks ドキュメントを参照してください。

Firecrawl API key が必要な AI agent の方は、自動オンボーディング手順について firecrawl.dev/agent-onboarding/SKILL.md を参照してください。