/crawl - Web コンテンツをクロールする

/crawl エンドポイントは、開始 URL からコンテンツをスクレイピングし、設定した深さまたはページ数の上限までサイト内のリンクをたどります。レスポンスは HTML、Markdown、JSON で返せます。

/crawl エンドポイントは REST API から利用できます。Browser Rendering - Edit 権限付きの カスタム API トークンを作成 してください。

https://api.cloudflare.com/client/v4/accounts/<account_id>/browser-rendering/crawl

• url (string)

追加のカスタマイズは オプションパラメーター を参照してください。

• 最新の Web コンテンツでナレッジベースや AI システム（RAG アプリケーション など）を構築する
• 調査、要約、監視のために、複数ページのコンテンツをスクレイピングして分析する

/crawl エンドポイントの利用は 2 ステップです。

1. クロールジョブを開始する — POST リクエストでクロールを開始し、ジョブ id を含むレスポンスを受け取ります。
2. クロールジョブの結果を取得する — GET リクエストでステータスまたは結果を取得します。

クロールジョブの最大実行時間は 7 日です。この時間内に終わらないジョブは、タイムアウトでキャンセルされます。ジョブ結果は完了後 14 日間利用でき、その後ジョブデータは削除されます。

url 付きの POST リクエストを送り、クロールジョブを開始します。API はすぐにジョブ id を返し、結果の取得に使います。追加のカスタマイズは オプションパラメーター を参照してください。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://developers.cloudflare.com/workers/"
  }'

レスポンス例:

{
	"success": true,
	"result": "c7f8s2d9-a8e7-4b6e-8e4d-3d4a1b2c3f4e"
}

受け取ったジョブ id を使い、ステータスの確認や結果の取得をします。

curl -X GET 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl/c7f8s2d9-a8e7-4b6e-8e4d-3d4a1b2c3f4e' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

レスポンスには、クロールジョブの現在の状態を示す status フィールドが含まれます。取りうるジョブステータスは次のとおりです。

• running — クロールジョブは実行中です。
• cancelled_due_to_timeout — クロールジョブが最大実行時間の 7 日を超えました。
• cancelled_due_to_limits — クロールジョブが アカウント制限 に達してキャンセルされました。
• cancelled_by_user — ユーザーがクロールジョブを手動でキャンセルしました。
• errored — クロールジョブでエラーが発生しました。
• completed — クロールジョブが正常に完了しました。

クロールジョブは非同期で動くため、エンドポイントを定期的にポーリングして完了を確認できます。リクエスト URL に ?limit=1 を付けるとレスポンスが軽くなります。必要なのはジョブの status だけで、クロール済みレコードの全件は不要です。

async function waitForCrawl(accountId, jobId, apiToken) {
	const maxAttempts = 60;
	const delayMs = 5000;

	for (let i = 0; i < maxAttempts; i++) {
		const response = await fetch(
			`https://api.cloudflare.com/client/v4/accounts/${accountId}/browser-rendering/crawl/${jobId}?limit=1`,
			{
				headers: {
					Authorization: `Bearer ${apiToken}`,
				},
			},
		);

		const data = await response.json();
		const status = data.result.status;

		if (status !== "running") {
			return data.result;
		}

		await new Promise((resolve) => setTimeout(resolve, delayMs));
	}

	throw new Error("Crawl job did not complete within timeout");
}

ジョブが終端ステータスになったら、limit パラメーターなしで全結果を取得します。次のクエリパラメーターで、結果の絞り込みとページネーションもできます。

• cursor — ページネーション用カーソル。レスポンスが 10 MB を超えると cursor 値が含まれます。クエリパラメーターとして渡し、次のページを取得します。
• limit — 返すレコードの最大数。
• status — URL ステータスで絞り込みます。queued、completed、disallowed、skipped、errored、cancelled です。

クエリパラメーター付きの例:

curl -X GET 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl/c7f8s2d9-a8e7-4b6e-8e4d-3d4a1b2c3f4e?cursor=10&limit=10&status=completed' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

レスポンス例:

{
	"result": {
		"id": "c7f8s2d9-a8e7-4b6e-8e4d-3d4a1b2c3f4e",
		"status": "completed",
		"browserSecondsUsed": 134.7,
		"total": 50,
		"finished": 50,
		"records": [
			{
				"url": "https://developers.cloudflare.com/workers/",
				"status": "completed",
				"markdown": "# Cloudflare Workers\nBuild and deploy serverless applications...",
				"metadata": {
					"status": 200,
					"title": "Cloudflare Workers · Cloudflare Workers docs",
					"url": "https://developers.cloudflare.com/workers/"
				}
			},
			{
				"url": "https://developers.cloudflare.com/workers/get-started/quickstarts/",
				"status": "completed",
				"markdown": "## Quickstarts\nGet up and running with a simple Hello World...",
				"metadata": {
					"status": 200,
					"title": "Quickstarts · Cloudflare Workers docs",
					"url": "https://developers.cloudflare.com/workers/get-started/quickstarts/"
				}
			}
			// ... 48 more entries omitted for brevity
		],
		"cursor": 10
	},
	"success": true
}

クロールしたページが HTTP エラー（402、403、500 など）を返すと、その URL のレコードは "status": "errored" になります。

この情報はクロール結果（ステップ 2）でのみ確認できます。開始時のレスポンス が返すのはジョブ id だけです。クロールジョブは非同期のため、開始時点ではページコンテンツを取得しません。

エラーになったレコードだけを見るには、status=errored で絞り込みます。

curl -X GET 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl/{job_id}?status=errored' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

レコードの status フィールドにはオリジンサーバーが返した HTTP ステータスコードが入り、html にはレスポンス本文が入ります。サイト所有者がクローラーをブロックする意図を把握するのに役立ちます。たとえば AI Crawl Control ↗ を使うサイトは、独自のステータスコードとメッセージを返すことがあります。

実行中のクロールジョブをキャンセルするには、受け取ったジョブ id を使います。

curl -X DELETE 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl/c7f8s2d9-a8e7-4b6e-8e4d-3d4a1b2c3f4e' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

キャンセルが成功すると 200 OK ステータスコードが返ります。ジョブステータスは cancelled に更新され、クロール待ちでキューに入っていたすべての URL もキャンセルされます。

必須の url に加え、クロールリクエストでは次のオプションパラメーターを使えます。これらは /crawl エンドポイント固有のパラメーターです。

render が true（デフォルト）のとき、クロールジョブは rejectResourceTypes、rejectRequestPattern、cookies、setExtraHTTPHeaders など、標準の Browser Run パラメーターもすべて使えます。render が false のときは、下表のクロール固有パラメーターだけが使えます。全一覧は API リファレンス を参照してください。

excludePatterns の優先度は常に高くなります。URL が除外ルールに一致すると、包含ルールに一致していてもスキップされます。

• ルールなし — すべてがインデックスされます。
• 除外のみ — 除外パターンに一致するもの以外は、すべてインデックスされます。
• 包含のみ — 包含パターンに一致するものだけがインデックスされ、それ以外は無視されます。

skipped ステータスは、クローラーが個別に発見・評価したあと、includeExternalLinks、includeSubdomains、includePatterns / excludePatterns などのクロール設定で取得しなかった URL に付きます。これらの URL を見るには、クロールジョブ結果を status=skipped で問い合わせます。

curl -X GET 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl/{job_id}?status=skipped' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

skipped は 1 件ずつ評価された URL だけを記録します。主に source: links（または source: all）のクロールに適用されます。このときクローラーはページから取得したリンクをたどり、設定と照合します。サイトマップからのクロール（source: sitemaps）では、設定外の URL は個別評価の前に一括で除外され、ジョブから完全に省かれます。skipped にはなりません。そのため、skipped の URL 集合は、クロールから外れたすべての URL の完全な一覧ではありません。

デフォルトの render: true では、crawl エンドポイントはヘッドレスブラウザーを起動し、ページの JavaScript を実行します。render: false では、JavaScript を実行せずに高速な HTML 取得をします。

ページがブラウザー側でコンテンツを組み立てる場合は render: true を使います。必要なコンテンツが最初の HTML レスポンスに含まれる場合は render: false を使います。

render: true のクロールはヘッドレスブラウザーを使い、通常の Browser Run の料金で課金されます。render: false のクロールはヘッドレスブラウザーではなく Workers 上で動きます。ベータ期間中、render: false のクロールは課金されません。ベータ終了後は Workers の料金 で課金されます。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://www.exampledocs.com/docs/",
    "crawlPurposes": ["search"],
    "contentUse": "reference",
    "limit": 50,
    "depth": 2,
    "formats": ["markdown"],
    "render": false,
    "maxAge": 7200,
    "modifiedSince": 1704067200,
    "source": "all",
    "options": {
      "includeExternalLinks": true,
      "includeSubdomains": true,
      "includePatterns": [
        "**/api/v1/*"
      ],
      "excludePatterns": [
        "*/learning-paths/*"
      ]
    }
}'

ドキュメントページだけをクロールし、特定のセクションを除外します。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/docs",
    "limit": 200,
    "depth": 5,
    "formats": ["markdown"],
    "options": {
      "includePatterns": [
        "https://example.com/docs/**"
      ],
      "excludePatterns": [
        "https://example.com/docs/changelog/**",
        "https://example.com/docs/archive/**"
      ]
    }
  }'

json 形式で構造化された商品データを抽出します。デフォルトでは Workers AI を使います。詳細は /json エンドポイント を参照してください。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://shop.example.com/products",
    "limit": 50,
    "formats": ["json"],
    "jsonOptions": {
      "prompt": "Extract product name, price, description, and availability",
      "response_format": {
        "type": "json_schema",
        "json_schema": {
          "name": "product",
          "properties": {
            "name": "string",
            "price": "number",
            "currency": "string",
            "description": "string",
            "inStock": "boolean"
          }
        }
      }
    },
    "options": {
      "includePatterns": [
        "https://shop.example.com/products/*"
      ]
    }
  }'

静的サイトを速くクロールするため、レンダリングせずに静的 HTML を取得します。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "limit": 100,
    "render": false,
    "formats": ["html", "markdown"]
  }'

HTTP 認証の背後にあるページや、カスタムヘッダー付きのページをクロールします。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://secure.example.com",
    "limit": 50,
    "authenticate": {
      "username": "user",
      "password": "pass"
    }
  }'

トークンベースの認証では、Cookie やカスタムヘッダーも使えます。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://api.example.com/docs",
    "limit": 100,
    "setExtraHTTPHeaders": {
      "X-API-Key": "your-api-key"
    }
  }'

コンテンツを動的に読み込むシングルページアプリケーションをクロールします。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://app.example.com",
    "limit": 50,
    "gotoOptions": {
      "waitUntil": "networkidle2",
      "timeout": 60000
    },
    "waitForSelector": {
      "selector": "[data-content-loaded]",
      "timeout": 30000,
      "visible": true
    }
  }'

画像とメディアをブロックしてクロールを速くします。rejectResourceTypes は render が true（デフォルト）のときだけ使えます。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "limit": 100,
    "rejectResourceTypes": [
      "image",
      "media",
      "font",
      "stylesheet"
    ]
  }'

クローラーは、次の順で URL を発見して処理します（デフォルトの source: all の場合）。

1. 開始 URL — リクエストで指定した URL。
2. サイトマップのリンク — サイトのサイトマップで見つかった URL。
3. ページ上のリンク — サイトマップにまだない、ページから取得したリンク。

source パラメーターで、クローラーが使うソースを変えられます。使える選択肢は次のとおりです。

• all — サイトマップとページ上のリンクの両方を使います（デフォルト）。
• sitemaps — サイトのサイトマップで見つかった URL だけをクロールします。
• links — ページ上のリンクだけをクロールし、サイトマップは無視します。

/crawl エンドポイントは robots.txt のディレクティブ（crawl-delay を含む）を尊重します。サイトの robots.txt に crawl-delay がない場合、クローラーは同じドメインへのリクエスト間にデフォルトで 0.5 秒の遅延を入れ、オリジンサーバーへの過負荷を避けます。/crawl がクロールしないよう指示された URL は、レスポンスに "status": "disallowed" として列挙されます。クロール対象サイトの robots.txt とサイトマップの設定は、robots.txt とサイトマップ を参照してください。/crawl エンドポイントによる自サイトへのアクセスを止めたい場合は、robots.txt でクローラーをブロックする を参照してください。

/crawl エンドポイントは User-Agent として CloudflareBrowserRenderingCrawler/1.0 を使います。ほかの Quick Actions エンドポイントとは異なります。この User-Agent はカスタマイズできません。ほかの Quick Actions エンドポイントと異なり、/crawl エンドポイントは userAgent パラメーターに対応していません。

デフォルトの User-Agent 文字列の一覧は、自動リクエストヘッダー を参照してください。

/crawl エンドポイントは、対象サイトの robots.txt にある Content Signals ↗ ディレクティブを尊重します。Content Signals は、サイト所有者が自動システムによるコンテンツ利用の希望を示す方法です。背景は Giving users choice with Cloudflare's new Content Signals Policy ↗ を参照してください。

サイト所有者は robots.txt に Content-Signal ディレクティブを含め、特定カテゴリの利用を許可または拒否できます。

• search — 検索インデックスの構築と、リンクと抜粋付きの検索結果の提供。
• ai-input — クエリ時に AI モデルへコンテンツを入力する（検索拡張生成やグラウンディングなど）。
• ai-train — AI モデルの学習またはファインチューニング。

たとえば、検索インデックスは許可し、AI 学習は拒否する robots.txt です。

User-Agent: *
Content-Signal: search=yes, ai-train=no
Allow: /

サイト所有者は use ディレクティブで、コンテンツを使える最大レベルを示すこともできます。緩い順のレベルは次のとおりです。

• immediate — 一時的な単一レスポンス利用。コンテンツは保持しません。
• reference — コンテンツの保持、インデックス、引用ができます。
• full — AI 学習を含む、制限のない利用。

たとえば、利用を reference に制限する robots.txt です。

User-Agent: *
Content-Signal: use=reference
Allow: /

/crawl エンドポイントは、yes/no の目的ディレクティブ（search、ai-input、ai-train）と、use レベルディレクティブの両方を適用します。

目的ディレクティブ

デフォルトで /crawl は 3 つの目的すべてを宣言します。["search", "ai-input", "ai-train"] です。対象サイトがこれらの Content Signals のいずれかを no にしている場合、crawlPurposes パラメーターで許可されない利用を除いて宣言を狭めない限り、開始時に 400 Bad Request エラーで拒否されます。

つまり:

1. サイトに Content Signals がない — クロールは通常どおり進みます。
2. サイトに Content Signals があり、宣言した目的がすべて許可されている — クロールは通常どおり進みます。
3. サイトが Content Signal を no にし、その目的が crawlPurposes に含まれる — クロールリクエストは 400 エラーとメッセージ Crawl disallowed by Content-Signal directive (purpose or use level) で拒否されます。

AI 学習は拒否するが検索は許可するサイトをクロールするには、必要な目的だけを crawlPurposes に設定します。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "crawlPurposes": ["search"],
    "formats": ["markdown"]
  }'

この例では、運用者が目的として search だけを宣言しているため、サイトが ai-train=no でもクロールは成功します。

利用レベルディレクティブ

contentUse パラメーターは、クロールしたコンテンツを使う意図のレベルを宣言します。緩い順に使える値は reference と full です。デフォルトは full です。

immediate レベルは contentUse の値として使えません。/crawl エンドポイントはクロールしたコンテンツを保存するため、一時的な単一レスポンス利用と両立しません。

宣言した contentUse レベルが、サイトが宣言した use レベルより緩い場合、クロールは拒否されます。たとえば:

1. サイトが use=full を設定している（または use を設定していない） — どの contentUse 値も許可されます。
2. サイトが use=reference を設定している — contentUse: "reference" のクロールは許可されますが、デフォルトの contentUse: "full" は拒否されます。
3. サイトが use=immediate を設定している — reference も full も宣言レベルを超えるため、すべてのクロールが拒否されます。

use=reference のサイトをクロールするには、contentUse を reference に設定します。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "contentUse": "reference",
    "formats": ["markdown"]
  }'

クロールジョブは完了したが records 配列が空、またはすべての URL が skipped か disallowed の場合:

• robots.txt によるブロック — クローラーは robots.txt ルールを尊重します。/crawl エンドポイントは自身を CloudflareBrowserRenderingCrawler/1.0 として識別します。対象サイトの robots.txt で、このユーザーエージェントが許可されているか確認してください。ブロックされた URL は "status": "disallowed" になります。
• パターンフィルターが厳しすぎる — includePatterns がサイト上のどの URL にも一致していない可能性があります。まずパターンなしでクロールし、URL を発見できることを確認してからパターンを追加してください。
• リンクが見つからない — 開始 URL にリンクがない可能性があります。source: "sitemaps" を使う、depth パラメーターを増やす、includeSubdomains または includeExternalLinks を true にする、を試してください。

クロールリクエストが 400 Bad Request とメッセージ Crawl disallowed by Content-Signal directive (purpose or use level) を返す場合、対象サイトの robots.txt に Content-Signal ディレクティブがあり、宣言した crawlPurposes の 1 つ以上を拒否しているか、宣言した contentUse レベルより厳しい use ディレクティブがあります。解決するには、サイトの robots.txt で Content-Signal: エントリを確認します。

• サイトが目的を no にしている場合は、必要な目的だけを crawlPurposes に設定します。たとえば、サイトが ai-train=no で、必要なのが検索インデックスだけなら "crawlPurposes": ["search"] を使います。
• サイトが use レベルを設定している場合は、それ以下のレベルを contentUse に設定します。たとえば、サイトが use=reference なら "contentUse": "reference" を使います。

詳細は Content Signals を参照してください。

クロールジョブが長時間 running のままの場合:

• ページ読み込みが遅い — JavaScript が重いページはレンダリングに時間がかかります。必要なコンテンツが最初の HTML にある場合は render: false を使います。
• レート制限 — クローラーはオリジンサーバーへの過負荷を避けるため、ドメインごとのレート制限を適用します。サイトの robots.txt に crawl-delay があれば尊重します。なければ、同じドメインへのリクエスト間にデフォルトで 0.5 秒の遅延を入れます。同じドメインを対象とする複数のクロールジョブを動かすと、ドメインごとのレート制限を共有するため、個別に動かすよりすべてのジョブが長くなります。
• 不要なリソース — コンテンツ抽出に不要なリソースは rejectResourceTypes でブロックします（例: image、media、font）。

cancelled_due_to_limits ステータスは、アカウントがブラウザー時間の上限に達したことを意味します。Workers Free プラン のアカウントは、1 日あたりのブラウザー利用が 10 分までです。対処するには:

• より高い 制限 を得るには、Workers Paid プランにアップグレード します。
• 静的コンテンツでは render: false を使い、ブラウザー時間を消費しないようにします。
• 可能なところでは maxAge を増やし、キャッシュ結果を使います。
• limit パラメーターを減らします。

json 形式が null または空の結果を返す場合:

• 明確なプロンプトを渡す — 抽出するデータと、ページ上の出現位置を具体的に指定します（例: 「メインの商品セクションから商品名、価格、説明を抽出する」）。
• レスポンススキーマを定義する — response_format と JSON スキーマで、期待する出力構造を強制します。
• カスタムモデルを使う — デフォルトの Workers AI モデルで望む結果が得られない場合は、custom_ai パラメーターで別のモデルを指定します。詳細は カスタムモデルを使う（BYO API キー） を参照してください。

質問やその他のエラーは、Browser Run の FAQ とトラブルシューティングガイド を参照してください。

質問がある場合やエラーが発生した場合は、Browser Run の FAQ とトラブルシューティングガイド を参照してください。