クロール

Firecrawl は複雑なウェブインフラストラクチャに対応しながら、網羅的なデータ抽出のためにウェブサイトを効率よくクロールします。プロセスは次のとおりです:

URL 分析: サイトマップをスキャンし、サイト全体をクロールしてリンクを特定
トラバーサル: すべてのサブページを見つけるためにリンクを再帰的にたどる
スクレイピング: 各ページからコンテンツを抽出し、JS やレート制限に対応
出力: データをクリーンな Markdown または構造化フォーマットに変換

これにより、任意の開始 URL からの徹底的なデータ収集を実現します。

Playground で試す

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

クローリング

/crawl エンドポイント

指定した URL と、その下にあるアクセス可能なサブページをクロールします。クロールジョブを送信し、進行状況を確認するためのジョブ ID を返します。

既定では、指定した URL の子ページでないサブリンクはクロール対象外になります。たとえば、website.com/blogs/ をクロールしても website.com/other-parent/blog-1 は返されません。website.com/other-parent/blog-1 も取得したい場合は、crawlEntireDomain パラメータを使用してください。website.com をクロールする際に blog.website.com のようなサブドメインもクロールするには、allowSubdomains パラメータを使用してください。

既定では、クローラーは URL を検出するためにサイトのサイトマップを利用します（sitemap: "include"）。sitemap: "skip" を設定すると、クローラーはルート URL から HTML リンクをたどって到達できるページのみを検出します。PDF のようなアセットや、サイトマップには記載されているものの、どの HTML ページからも直接リンクされていない深い階層のページは取得されません。最大限のカバレッジを得るには、既定の sitemap: "include" 設定のままにしておくことを推奨します。

インストール

# pip install firecrawl-py

from firecrawl import Firecrawl

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

# npm install @mendable/firecrawl-js

import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

# npmでグローバルにインストール
npm install -g firecrawl

# 認証（初回セットアップ）
firecrawl login

使い方

from firecrawl import Firecrawl

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

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

import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const docs = await firecrawl.crawl('https://docs.firecrawl.dev', { limit: 10 });
console.log(docs);

curl -s -X POST "https://api.firecrawl.dev/v2/crawl" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.firecrawl.dev",
    "limit": 10
  }'

# クロールジョブを開始（ジョブIDを返す）
firecrawl crawl https://firecrawl.dev

# 進行状況を表示しながら完了を待機
firecrawl crawl https://firecrawl.dev --wait --progress --limit 100

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

クロールでのスクレイプオプション

Scrape エンドポイントのすべてのオプションは、scrapeOptions（JS）/ scrape_options（Python）経由で Crawl でも利用できます。これらはクローラーがスクレイプするすべてのページに適用されます（フォーマット、プロキシ、キャッシュ、アクション、ロケーション、タグなど）。詳細は Scrape API Reference を参照してください。

import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });

// スクレイプオプション付きでクロール
const crawlResponse = await firecrawl.crawl('https://example.com', {
  limit: 100,
  scrapeOptions: {
    formats: [
      'markdown',
      {
        type: 'json',
        schema: { type: 'object', properties: { title: { type: 'string' } } },
      },
    ],
    proxy: 'auto',
    maxAge: 600000,
    onlyMainContent: true,
  },
});

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
    }
)

API レスポンス

cURL または starter メソッドを使用している場合、クロールのステータスを確認するための ID が返されます。

SDK を使用している場合は、以下のメソッドで waiter と starter の動作の違いをご確認ください。

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

クロールジョブの確認

クロールジョブのステータスを確認し、結果を取得します。

ジョブの結果は、完了後24時間は API 経由で取得できます。この期間を過ぎても、activity logs からクロール履歴と結果を参照できます。

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

status = firecrawl.get_crawl_status("<crawl-id>")
print(status)

const status = await firecrawl.getCrawlStatus("<crawl-id>");
console.log(status);

# クロール開始後は、jobId でステータスをポーリングする
curl -s -X GET "https://api.firecrawl.dev/v2/crawl/<jobId>" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

# ジョブIDを使用してクロールステータスを確認
firecrawl crawl <job-id>

レスポンスの処理

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

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
      }
    },
    ...
  ]
}

{
  "status": "完了",
  "total": 36,
  "completed": 36,
  "creditsUsed": 36,
  "expiresAt": "2024-00-00T00:00:00.000Z",
  "next": "https://api.firecrawl.dev/v2/crawl/123-456-789?skip=26",
  "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 の利用方法は 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)

import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({apiKey: "fc-YOUR_API_KEY"});

const crawlResponse = await firecrawl.crawl('https://firecrawl.dev', {
  limit: 100,
  scrapeOptions: {
    formats: ['markdown', 'html'],
  }
})

console.log(crawlResponse)

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

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
    }
  ),
  ...
]

{
  success: true,
  status: "completed",
  completed: 100,
  total: 100,
  creditsUsed: 100,
  expiresAt: "2025-04-23T19:28:45.000Z",
  data: [
    {
      markdown: "[7日目 - Launch Week III：インテグレーション・デー 4月 ...",
      html: `<!DOCTYPE html><html lang="en" class="light" style="color...`,
      metadata: [Object],
    },
    ...
  ]
}

開始してステータス確認（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)

import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const { id } = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 10 });
console.log(id);

// クロールの進行状況を確認する
const status = await firecrawl.getCrawlStatus(id);
console.log(status);

curl -s -X POST "https://api.firecrawl.dev/v2/crawl" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.firecrawl.dev",
    "limit": 10
  }'

# クロールを開始(非同期、ジョブIDを即座に返します)
firecrawl crawl https://firecrawl.dev --limit 100

# 後でステータスを確認
firecrawl crawl <job-id>

Crawl WebSocket

Firecrawl の WebSocket ベースのメソッド「Crawl URL and Watch」は、リアルタイムでのデータ抽出と監視を実現します。URL を指定してクロールを開始し、ページ上限、許可ドメイン、出力フォーマットなどのオプションでカスタマイズできます。即時のデータ処理に最適です。

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())

import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR-API-KEY' });

// クロールを開始して監視する
const { id } = await firecrawl.startCrawl('https://mendable.ai', {
  excludePaths: ['blog/*'],
  limit: 5,
});

const watcher = firecrawl.watcher(id, { kind: 'crawl', pollInterval: 2, timeout: 120 });

watcher.on('document', (doc) => {
  console.log('DOC', doc);
});

watcher.on('error', (err) => {
  console.error('ERR', err?.error || err);
});

watcher.on('done', (state) => {
  console.log('DONE', state.status);
});

// 監視を開始（WS と HTTP のフォールバック）
await watcher.start();

クロール Webhook

クロールの進行に合わせてリアルタイム通知を受け取れるよう、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"]
      }
    }'

クイックリファレンス

イベントタイプ:

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 ドキュメントを参照してください。

はじめに

新機能

コア機能

開発者向けガイド

ウェブフック

ユースケース

貢献方法

Playground で試す

クローリング

/crawl エンドポイント

インストール

使い方

クロールでのスクレイプオプション

API レスポンス

クロールジョブの確認

レスポンスの処理

SDK メソッド

Crawl WebSocket

クロール Webhook

クイックリファレンス

セキュリティ: Webhook シグネチャの検証

詳細ドキュメント

Playground で試す

​クローリング

​/crawl エンドポイント

​インストール

​使い方

​クロールでのスクレイプオプション

​API レスポンス

​クロールジョブの確認

​レスポンスの処理

​SDK メソッド

​Crawl WebSocket

​クロール Webhook

​クイックリファレンス

​セキュリティ: Webhook シグネチャの検証

​詳細ドキュメント

クローリング

/crawl エンドポイント

インストール

使い方

クロールでのスクレイプオプション

API レスポンス

クロールジョブの確認

レスポンスの処理

SDK メソッド

Crawl WebSocket

クロール Webhook

クイックリファレンス

セキュリティ: Webhook シグネチャの検証

詳細ドキュメント