イベントタイプ - Firecrawl Docs

Firecrawl はジョブのライフサイクルの各段階で webhook イベントを送信するため、ポーリングしなくても進捗を追跡し、結果を取得し、失敗をリアルタイムで処理できます。

クイックリファレンス#

Event	Trigger
`crawl.started`	クロールジョブの処理が開始される
`crawl.page`	クロール中にページがスクレイピングされる
`crawl.completed`	クロールジョブが完了し、すべてのページが処理される
`batch_scrape.started`	バッチスクレイプジョブの処理が開始される
`batch_scrape.page`	バッチスクレイプ中にURLがスクレイピングされる
`batch_scrape.completed`	バッチ内のすべてのURLが処理される
`extract.started`	抽出ジョブの処理が開始される
`extract.completed`	抽出が正常に完了する
`extract.failed`	抽出が失敗する
`agent.started`	エージェントジョブの処理が開始される
`agent.action`	エージェントがツール (スクレイピング、検索など) を実行する
`agent.completed`	エージェントが正常に完了する
`agent.failed`	エージェントでエラーが発生する
`agent.cancelled`	エージェントジョブがユーザーによってキャンセルされる
`monitor.page`	監視対象ページのスクレイピングが完了する
`monitor.check.completed`	monitor チェックが完了し、ページ単位の変更を利用できる

ペイロード構造#

すべてのWebhookイベントは、この共通の構造を持ちます。

{  "success": true,  "type": "crawl.page",  "id": "550e8400-e29b-41d4-a716-446655440000",  "data": [...],  "metadata": {}}

Field	Type	Description
`success`	boolean	操作が成功したかどうか
`type`	string	イベントタイプ (例: `crawl.page`)
`id`	string	ジョブID
`data`	array or object	イベント固有のデータ (下記の例を参照)
`metadata`	object	Webhook 設定で指定したカスタムメタデータ
`error`	string	エラーメッセージ (`success` が `false` の場合)

クロールイベント#

`crawl.started`#

クロールジョブの処理が開始されるタイミングで送信されます。

{  "success": true,  "type": "crawl.started",  "id": "550e8400-e29b-41d4-a716-446655440000",  "data": [],  "metadata": {}}

`crawl.page`#

クロール中にスクレイピングされた各ページごとに送信されます。data 配列にはページのコンテンツとメタデータが含まれます。

{  "success": true,  "type": "crawl.page",  "id": "550e8400-e29b-41d4-a716-446655440000",  "data": [    {      "markdown": "# Page content...",      "metadata": {        "title": "Page Title",        "description": "ページの説明",        "url": "https://example.com/page",        "statusCode": 200,        "contentType": "text/html",        "scrapeId": "550e8400-e29b-41d4-a716-446655440001",        "sourceURL": "https://example.com/page",        "proxyUsed": "basic",        "cacheState": "hit",        "cachedAt": "2025-09-03T21:11:25.636Z",        "creditsUsed": 1      }    }  ],  "metadata": {}}

`crawl.completed`#

クロール処理が完了し、すべてのページの処理が終了したときに送信されます。

{  "success": true,  "type": "crawl.completed",  "id": "550e8400-e29b-41d4-a716-446655440000",  "data": [],  "metadata": {}}

バッチスクレイプイベント#

`batch_scrape.started`#

バッチスクレイプジョブの処理開始時に送信されます。

{  "success": true,  "type": "batch_scrape.started",  "id": "550e8400-e29b-41d4-a716-446655440000",  "data": [],  "metadata": {}}

`batch_scrape.page`#

バッチ内でスクレイプされる各URLごとに送信されます。data 配列にはページコンテンツとメタデータが含まれます。

{  "success": true,  "type": "batch_scrape.page",  "id": "550e8400-e29b-41d4-a716-446655440000",  "data": [    {      "markdown": "# Page content...",      "metadata": {        "title": "Page Title",        "description": "ページの説明",        "url": "https://example.com",        "statusCode": 200,        "contentType": "text/html",        "scrapeId": "550e8400-e29b-41d4-a716-446655440001",        "sourceURL": "https://example.com",        "proxyUsed": "basic",        "cacheState": "miss",        "cachedAt": "2025-09-03T23:30:53.434Z",        "creditsUsed": 1      }    }  ],  "metadata": {}}

`batch_scrape.completed`#

バッチ内のすべてのURLの処理が完了したときに送信されます。

{  "success": true,  "type": "batch_scrape.completed",  "id": "550e8400-e29b-41d4-a716-446655440000",  "data": [],  "metadata": {}}

Monitorイベント#

`monitor.page`#

監視対象ページのスクレイピングが完了するたびに送信されます。このイベントはスクレイプワーカー経由で発行されるため、monitor check 全体の結果が確定する前に届きます。

monitor.page

{  "success": true,  "type": "monitor.page",  "id": "019df960-5f2a-75fb-a98b-bd2d32ca67d4",  "webhookId": "f1e2d3c4-0000-0000-0000-000000000000",  "data": [    {      "monitorId": "019df960-06e7-7383-9d89-82c0113dc31a",      "checkId": "019df960-5f2a-75fb-a98b-bd2d32ca67d4",      "url": "https://example.com/blog",      "status": "changed",      "previousScrapeId": "019df94f-82c3-7e41-81f0-00c72b2d9c52",      "currentScrapeId": "019df960-73ee-7ac2-97a9-fb0e442c21f1",      "error": null,      "isMeaningful": true,      "judgment": {        "meaningful": true,        "confidence": "high",        "reason": "The page headline changed to announce a new release cadence.",        "meaningfulChanges": [          {            "type": "changed",            "before": "Welcome to our weekly update.",            "after": "Welcome to our weekly update — now with daily releases!",            "reason": "The headline changed in a way that matches the monitor goal."          }        ]      },      "diff": {        "text": "--- previous\n+++ current\n@@ -1,3 +1,3 @@\n # Latest posts\n-Welcome to our weekly update.\n+Welcome to our weekly update — now with daily releases!\n"      }    }  ],  "metadata": {    "environment": "production"  }}

`monitor.check.completed`#

monitor のチェックが完了したときに送信されます。data オブジェクトには、チェックの status と集計件数が含まれます。ページ単位の結果は、monitor.page イベントでのみ送信されるか、monitor check API から返されます。

monitor.check.completed

{  "success": true,  "type": "monitor.check.completed",  "id": "019df960-5f2a-75fb-a98b-bd2d32ca67d4",  "webhookId": "f1e2d3c4-0001-0000-0000-000000000000",  "data": [    {      "monitorId": "019df960-06e7-7383-9d89-82c0113dc31a",      "checkId": "019df960-5f2a-75fb-a98b-bd2d32ca67d4",      "status": "completed",      "summary": {        "totalPages": 2,        "same": 1,        "changed": 1,        "new": 0,        "removed": 0,        "error": 0      }    }  ],  "metadata": {    "environment": "production"  }}

ページエラーなしでチェックが完了した場合、success は true です。一部のみ完了したチェックまたは失敗したチェックでは、success は false となり、error にメッセージが含まれることがあります。

抽出イベント#

`extract.started`#

抽出処理が開始されると送信されます。

{  "success": true,  "type": "extract.started",  "id": "550e8400-e29b-41d4-a716-446655440000",  "data": [],  "metadata": {}}

`extract.completed`#

抽出オペレーションが正常に完了したときに送信されます。data 配列には、抽出されたデータと使用状況情報が含まれます。

{  "success": true,  "type": "extract.completed",  "id": "550e8400-e29b-41d4-a716-446655440000",  "data": [    {      "success": true,      "data": { "siteName": "Example Site", "category": "Technology" },      "extractId": "550e8400-e29b-41d4-a716-446655440000",      "llmUsage": 0.0020118,      "totalUrlsScraped": 1,      "sources": {        "siteName": ["https://example.com"],        "category": ["https://example.com"]      }    }  ],  "metadata": {}}

`extract.failed`#

抽出処理でエラーが発生したときに送信されます。error フィールドに失敗理由が格納されます。

{  "success": false,  "type": "extract.failed",  "id": "550e8400-e29b-41d4-a716-446655440000",  "data": [],  "error": "データの抽出に失敗しました：タイムアウトを超過しました",  "metadata": {}}

エージェントイベント#

/v2/agent で webhook を指定して開始されたジョブに対して送信されます。

`agent.started`#

エージェントのジョブの処理が開始されると送信されます。

{  "success": true,  "type": "agent.started",  "id": "550e8400-e29b-41d4-a716-446655440000",  "data": [],  "metadata": {}}

`agent.action`#

各ツール (scrape、search など) の実行ごとに送信されます。

{  "success": true,  "type": "agent.action",  "id": "550e8400-e29b-41d4-a716-446655440000",  "data": [    {      "creditsUsed": 5,      "action": "mcp__tools__scrape",      "input": {        "url": "https://example.com"      }    }  ],  "metadata": {}}

Note

action イベントの creditsUsed の値は、これまでに使用されたクレジット総量の推定値です。最終的かつ正確なクレジット数は、completed、failed、cancelled イベントでのみ取得できます。

`agent.completed`#

エージェントの処理が正常に完了したときに送信されます。data 配列には、抽出されたデータと消費されたクレジットの合計が含まれます。

{  "success": true,  "type": "agent.completed",  "id": "550e8400-e29b-41d4-a716-446655440000",  "data": [    {      "creditsUsed": 15,      "data": {        "company": "Example Corp",        "industry": "Technology",        "founded": 2020      }    }  ],  "metadata": {}}

`agent.failed`#

エージェントでエラーが発生したときに送信されます。error フィールドには失敗理由が含まれます。

{  "success": false,  "type": "agent.failed",  "id": "550e8400-e29b-41d4-a716-446655440000",  "data": [    {      "creditsUsed": 8    }  ],  "error": "最大クレジット数を超過しました",  "metadata": {}}

`agent.cancelled`#

ユーザーがエージェントジョブをキャンセルしたときに送信されます。

{  "success": false,  "type": "agent.cancelled",  "id": "550e8400-e29b-41d4-a716-446655440000",  "data": [    {      "creditsUsed": 3    }  ],  "metadata": {}}

イベントのフィルタリング#

デフォルトではすべてのイベントを受信します。特定のイベントだけを受信したい場合は、Webhook の設定で events 配列を指定してください。

{  "url": "https://your-app.com/webhook",  "events": ["completed", "failed"]}

ジョブの完了だけ分かればよく、ページ単位の更新は不要な場合に便利です。

クイックリファレンス#

ペイロード構造#

クロールイベント#

crawl.started#

crawl.page#

crawl.completed#

バッチスクレイプイベント#

batch_scrape.started#

batch_scrape.page#

batch_scrape.completed#

Monitorイベント#

monitor.page#

monitor.check.completed#

抽出イベント#

extract.started#

extract.completed#

extract.failed#

エージェント イベント#

agent.started#

agent.action#

agent.completed#

agent.failed#

agent.cancelled#