クロール | Firecrawl

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

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

Playground で試す

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

インストール

# pip install firecrawl-py

from firecrawl import Firecrawl

firecrawl = Firecrawl(
  # 開始にAPIキーは不要です — より高いrate limitsが必要な場合は追加してください:
  # api_key="fc-YOUR-API-KEY",
)

// npm install firecrawl

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({
  // 開始にAPIキーは不要です — より高いrate limitsのために追加してください:
  // apiKey: "fc-YOUR-API-KEY",
});

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

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

基本的な使い方

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

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 'firecrawl';

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 をカバーできるか確認し、不足している場合は 402 (Payment Required) エラーを返します。これを避けるには、意図したクロール規模に合わせて、limit: 100 のようにより小さい limit を設定してください。特定のオプションには追加クレジットが必要です。JSONモードはページごとに追加で 4 クレジット、強化プロキシはページごとに追加で 4 クレジット、PDF 解析は PDF のページごとに 1 クレジットを消費します。

スクレイピングのオプション

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

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

import { Firecrawl } from 'firecrawl';

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

クロールステータスの確認

ジョブ ID を使用してクロールのステータスをポーリングし、結果を取得します。

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>

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

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

レスポンスの処理

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

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 で crawl を使う方法は 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 'firecrawl';

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: "[Day 7 - Launch Week III.Integrations DayApril ...",
      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 'firecrawl';

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>

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

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

WebSocket によるリアルタイム結果

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

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 'firecrawl';

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

Webhooks

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

イベントタイプ

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

設定リファレンス

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

Parameter	Type	Default	Description
`url`	`string`	(required)	クロール開始元の URL
`limit`	`integer`	`10000`	クロールするページの最大数
`maxDiscoveryDepth`	`integer`	(none)	URL 内の `/` セグメント数ではなく、リンクの発見ホップ数に基づくルート URL からの最大深度。ページ上で新しい URL が見つかるたびに、その URL には発見元のページより 1 つ深い深度が割り当てられます。ルートサイトおよびサイトマップに含まれるページの発見深度は 0 です。最大深度のページもスクレイプされますが、そのページ上のリンクはたどりません。
`includePaths`	`string[]`	(none)	含める URL パスの正規表現パターン。一致するパスのみをクロールします。
`excludePaths`	`string[]`	(none)	クロール対象から除外する URL パスの正規表現パターン
`regexOnFullURL`	`boolean`	`false`	`includePaths`/`excludePaths` を、パスのみではなく完全な URL (クエリパラメータを含む) に対して照合します
`crawlEntireDomain`	`boolean`	`false`	子パスだけでなく、同一ドメイン内の兄弟 URL や親 URL への内部リンクもたどります
`allowSubdomains`	`boolean`	`false`	メインドメインのサブドメインへのリンクもたどります
`allowExternalLinks`	`boolean`	`false`	外部サイトへのリンクもたどります
`sitemap`	`string`	`"include"`	サイトマップの扱い: `"include"` (デフォルト) 、`"skip"`、または `"only"`
`ignoreQueryParameters`	`boolean`	`false`	クエリパラメータが異なっていても、同じパスの再スクレイピングを避けます
`ignoreRobotsTxt`	`boolean`	`false`	Web サイトの robots.txt のルールを無視します。Enterprise only — 有効化するには support@firecrawl.com にお問い合わせください。
`robotsUserAgent`	`string`	(none)	robots.txt の評価に使用するカスタム User-Agent 文字列。設定すると、robots.txt はこの User-Agent で取得され、デフォルトではなくこの User-Agent に対してルールが照合されます。Enterprise only — 有効化するには support@firecrawl.com にお問い合わせください。
`delay`	`number`	(none)	レート制限を順守するためのスクレイプ間の遅延 (秒)。これを設定すると、同時実行数は 1 に固定されます。
`maxConcurrency`	`integer`	(none)	同時スクレイプの最大数。デフォルトでは、チームの同時実行数上限が使用されます。
`scrapeOptions`	`object`	(none)	すべてのスクレイプ対象ページに適用されるオプション (フォーマット、プロキシ、キャッシュ、アクションなど)
`webhook`	`object`	(none)	リアルタイム通知用の webhook 設定
`prompt`	`string`	(none)	クロールオプションを生成するための自然言語プロンプト。明示的に設定したパラメータは、生成された対応項目より優先されます。

重要な詳細

デフォルトでは、crawl は指定した URL の配下にないサブリンクを無視します。たとえば、website.com/blogs/ をクロールした場合、website.com/other-parent/blog-1 は返されません。兄弟パスや親パスも含めるには、crawlEntireDomain パラメータを使用します。website.com のクロール時に blog.website.com のようなサブドメインも対象にするには、allowSubdomains パラメータを使用します。

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

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

Playground で試す

​インストール

​基本的な使い方

​スクレイピングのオプション

​クロールステータスの確認

​レスポンスの処理

​SDK メソッド

​クロールして待つ

​開始して後で確認

​WebSocket によるリアルタイム結果

​Webhooks

​イベントタイプ

​ペイロード

​Webhook シグネチャの検証

​設定リファレンス

​重要な詳細

インストール

基本的な使い方

スクレイピングのオプション

クロールステータスの確認

レスポンスの処理

SDK メソッド

クロールして待つ

開始して後で確認

WebSocket によるリアルタイム結果

Webhooks

イベントタイプ

ペイロード

Webhook シグネチャの検証

設定リファレンス

重要な詳細