クロール

Firecrawl はブロッカーを回避しながら、網羅的なデータ抽出のためにウェブサイトを効率よくクロールします。プロセスは次のとおりです:

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

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

クローリング

/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 パラメータを使用してください。

インストール

# pip install firecrawl-py

from firecrawl import Firecrawl

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

使い方

from firecrawl import Firecrawl

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

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

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

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

API レスポンス

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

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

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

クロールジョブの確認

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

このエンドポイントは、進行中のクロール、または直近に完了したクロールに対してのみ機能します。

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

レスポンスの処理

レスポンスはクロールのステータスによって異なります。未完了のレスポンス、またはサイズが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
      }
    },
    ...
  ]
}

SDK メソッド

SDK の利用方法は 2 通りあります:

クロールして待つ（crawl）:
- クロールの完了を待機し、完全なレスポンスを返します
- ページネーションを自動処理します
- ほとんどのユースケースで推奨

from firecrawl import Firecrawl, 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)

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

クロール 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"]
      }
    }'

イベントタイプ、ペイロード構造、実装例などを含む包括的な webhook のドキュメントは、Webhooks ドキュメントを参照してください。

クイックリファレンス

イベントタイプ:

crawl.started - クロールが開始されたとき
crawl.page - 各ページのスクレイピングに成功したとき
crawl.completed - クロールが終了したとき
crawl.failed - クロール中にエラーが発生した場合

基本ペイロード:

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

Webhook の詳細な設定、セキュリティのベストプラクティス、トラブルシューティングについては、Webhooks ドキュメントをご覧ください。

はじめに

標準機能

エージェント機能

Webhook

ユースケース

貢献

クローリング

/crawl エンドポイント

インストール

使い方

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

API レスポンス

クロールジョブの確認

レスポンスの処理

SDK メソッド

Crawl WebSocket

クロール Webhook

クイックリファレンス

はじめに

標準機能

エージェント機能

Webhook

ユースケース

貢献

​クローリング

​/crawl エンドポイント

​インストール

​使い方

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

​API レスポンス

​クロールジョブの確認

​レスポンスの処理

​SDK メソッド

​Crawl WebSocket

​クロール Webhook

​クイックリファレンス

クローリング

/crawl エンドポイント

インストール

使い方

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

API レスポンス

クロールジョブの確認

レスポンスの処理

SDK メソッド

Crawl WebSocket

クロール Webhook

クイックリファレンス