# クロール
> ウェブサイトを再帰的にクロールし、各ページからコンテンツを取得します
import InstallationPython from '/snippets/ja/v2/installation/python.mdx';
import InstallationNode from '/snippets/ja/v2/installation/js.mdx';
import InstallationCLI from '/snippets/ja/v2/installation/cli.mdx';
import CrawlPython from '/snippets/ja/v2/crawl/base/python.mdx';
import CrawlNode from '/snippets/ja/v2/crawl/base/js.mdx';
import CrawlCURL from '/snippets/ja/v2/crawl/base/curl.mdx';
import CrawlCLI from '/snippets/ja/v2/crawl/base/cli.mdx';
import CheckCrawlJobPython from '/snippets/ja/v2/crawl-status/short/python.mdx';
import CheckCrawlJobNode from '/snippets/ja/v2/crawl-status/short/js.mdx';
import CheckCrawlJobCURL from '/snippets/ja/v2/crawl-status/short/curl.mdx';
import CheckCrawlJobCLI from '/snippets/ja/v2/crawl-status/short/cli.mdx';
import CheckCrawlJobOutputScraping from '/snippets/ja/v2/crawl-status/base/output-scraping.mdx';
import CheckCrawlJobOutputCompleted from '/snippets/ja/v2/crawl-status/base/output-completed.mdx';
import CrawlWebSocketPython from '/snippets/ja/v2/crawl-websocket/base/python.mdx';
import CrawlWebSocketNode from '/snippets/ja/v2/crawl-websocket/base/js.mdx';
import CrawlWebhookCURL from '/snippets/ja/v2/crawl-webhook/base/curl.mdx';
import PythonCrawlExample from '/snippets/ja/v2/crawl/sdk-example/python.mdx';
import NodeCrawlExample from '/snippets/ja/v2/crawl/sdk-example/js.mdx';
import PythonCrawlExampleResponse from '/snippets/ja/v2/crawl/sdk-example/python-response.mdx';
import NodeCrawlExampleResponse from '/snippets/ja/v2/crawl/sdk-example/js-response.mdx';
import StartCrawlPython from '/snippets/ja/v2/start-crawl/base/python.mdx';
import StartCrawlNode from '/snippets/ja/v2/start-crawl/base/js.mdx';
import StartCrawlCURL from '/snippets/ja/v2/start-crawl/base/curl.mdx';
import StartCrawlCLI from '/snippets/ja/v2/start-crawl/base/cli.mdx';
import StartCrawlOutput from '/snippets/ja/v2/start-crawl/base/output.mdx';
import PlaygroundCTA from "/snippets/ja/shared/playground-cta-crawl.mdx";
Crawl は URL を Firecrawl に送信し、到達可能なすべてのサブページを再帰的に検出してスクレイピングします。サイトマップ、JavaScript レンダリング、レート制限を自動的に処理し、各ページについてクリーンな Markdown または構造化データを返します。
* サイトマップとリンクの再帰的なたどりによってページを検出
* パスのフィルタリング、深さ制限、サブドメインや外部リンクの制御をサポート
* ポーリング、WebSocket、または Webhook で結果を返す
## インストール
## 基本的な使い方
開始 URL を指定して `POST /v2/crawl` を呼び出し、クロールジョブを送信します。このエンドポイントは、結果をポーリングするために使用するジョブ ID を返します。
クロールされたページ 1 件ごとに 1 クレジットを消費します。デフォルトのクロール `limit` は 10,000 ページです。開始前に、クロールエンドポイントは残りのクレジットで `limit` をカバーできるか確認し、不足している場合は **402 (Payment Required) ** エラーを返します。これを避けるには、意図したクロール規模に合わせて、`limit: 100` のようにより小さい `limit` を設定してください。特定のオプションには追加クレジットが必要です。JSONモードはページごとに追加で 4 クレジット、PDF 解析は PDF のページごとに 1 クレジットを消費します。
### スクレイピングのオプション
[/scrape エンドポイント](/ja/api-reference/endpoint/scrape) のすべてのオプションは、`scrapeOptions` (JS) / `scrape_options` (Python) を使ってクロールでも利用できます。これらは、クローラーがスクレイピングするすべてのページに適用されます (フォーマット、プロキシ、キャッシュ、アクション、ロケーション、タグを含む) 。
```python 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
}
)
```
```js Node
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 を使用してクロールのステータスをポーリングし、結果を取得します。
ジョブの結果は、完了後24時間は API 経由で取得できます。この期間を過ぎても、[activity logs](https://www.firecrawl.dev/app/logs) からクロール履歴と結果を参照できます。
クロール結果の `data` 配列に含まれているページは、対象サイトが 404 のような HTTP エラーを返した場合でも、Firecrawl がスクレイピングに成功したページです。`metadata.statusCode` フィールドには、対象サイトから返された HTTP ステータスコードが含まれます。Firecrawl 自体がスクレイピングに失敗したページ (ネットワークエラー、タイムアウト、robots.txt によるブロックなど) を取得するには、専用の [Get Crawl Errors](/ja/api-reference/endpoint/crawl-get-errors) エンドポイント (`GET /crawl/{id}/errors`) を使用してください。
### レスポンスの処理
レスポンスはクロールのステータスによって異なります。未完了のレスポンス、またはサイズが10MBを超える大きなレスポンスの場合は、`next` URLパラメータが付与されます。次の10MBのデータを取得するには、このURLにリクエストしてください。`next` パラメータがない場合は、クロールデータの終端を示します。
`skip` と `next` のパラメータが関係するのは、API を直接呼び出す場合のみです。
SDK を使用している場合は、ページネーションは自動的に処理され、すべての
結果が一度に返されます。
## SDK メソッド
SDK で crawl を使う方法は 2 通りあります。
### クロールして待つ
`crawl` メソッドはクロールの完了を待機し、完全なレスポンスを返します。ページネーションを自動処理します。ほとんどのユースケースで推奨されます。
レスポンスには、クロールのステータスと収集された全データが含まれます:
### 開始して後で確認
`startCrawl` / `start_crawl` メソッドは即時にクロール ID を返します。その後、ステータスを手動でポーリングして確認します。これは、長時間のクロールや独自のポーリングロジックに有用です。
最初のレスポンスではジョブ ID が返されます:
## WebSocket によるリアルタイム結果
watcher メソッドでは、ページのクロール中にリアルタイムで更新を受け取れます。クロールを開始し、その後イベントを購読することで、データを即座に処理できます。
## Webhooks
クロールの進行に合わせてリアルタイム通知を受け取れるよう、webhook を設定できます。これにより、クロール全体の完了を待たずに、スクレイプされたページを随時処理できます。
### イベントタイプ
| Event | Description |
| ----------------- | ---------------------- |
| `crawl.started` | クロールが開始されたときに発火します |
| `crawl.page` | スクレイプに成功した各ページごとに発火します |
| `crawl.completed` | クロールが完了したときに発火します |
| `crawl.failed` | クロール中にエラーが発生した場合に発火します |
### ペイロード
```json
{
"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 が正当で改ざんされていないことを確認するために、必ずこのシグネチャを検証してください。
1. アカウント設定の [Advanced タブ](https://www.firecrawl.dev/app/settings?tab=advanced) から webhook secret を取得する
2. `X-Firecrawl-Signature` ヘッダーからシグネチャを取得する
3. 取得した secret を使い、生のリクエストボディに対して HMAC-SHA256 を計算する
4. タイミング攻撃耐性のある関数を使って、計算結果とヘッダーのシグネチャを比較する
シグネチャを最初に検証せずに webhook を処理してはいけません。`X-Firecrawl-Signature` ヘッダーには、`sha256=abc123def456...` という形式でシグネチャが含まれています。
JavaScript と Python による完全な実装例については、[Webhook セキュリティのドキュメント](/ja/webhooks/security) を参照してください。詳細なイベントペイロード、ペイロード構造、高度な設定、トラブルシューティングを含む包括的な webhook ドキュメントについては、[Webhooks ドキュメント](/ja/webhooks/overview) を参照してください。
## 設定リファレンス
クロールジョブの送信時に指定できる全パラメータ:
| 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` | 外部サイトへのリンクもたどります。外部リンクは 1 ホップのみたどられ (そのリンク先のリンクはクロールされません) 、外部サイトのホームページを指すリンクはスキップされます — [外部リンク](#external-links) を参照してください。 |
| `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 クレジットが追加され、PDF の解析には PDF 1 ページごとに 1 クレジットかかります。
* **結果の有効期限**: ジョブの結果は、完了後 24 時間は API 経由で利用できます。その後は、[アクティビティログ](https://www.firecrawl.dev/app/logs)で結果を確認してください。
* **クロールエラー**: `data` 配列には、Firecrawl が正常にスクレイピングしたページが含まれます。ネットワークエラー、タイムアウト、または robots.txt によるブロックで失敗したページを取得するには、[Get Crawl Errors](/ja/api-reference/endpoint/crawl-get-errors) エンドポイントを使用します。
* **外部リンク**: `allowExternalLinks: true` を指定すると、クローラーはドメイン外を指すリンクをたどり、リンク先の各ページを 1 回スクレイピングします。ただし、その外部ページで見つかったリンクをさらにクロールすることはありません。無関係なサイト全体を取り込むことを避けるため、外部サイトの**ホームページ** (パスのないルート URL。例: `https://example.com/`) へのリンクは意図的にスキップされます。これらは [Get Crawl Errors](/ja/api-reference/endpoint/crawl-get-errors) にコード `EXTERNAL_LINK` として表示されます。リダイレクトは宛先までたどられます。これには正規 URL に解決されるリンク (たとえば `http → https` や `www` バリアント) も含まれるため、外部ホームページに到達するリダイレクトのみがスキップされます。
* **非決定的な結果**: 同じ設定で実行しても、クロール結果は実行ごとに異なる場合があります。ページは並行してスクレイピングされるため、リンクが検出される順序はネットワークのタイミングや、どのページの読み込みが先に完了するかに左右されます。そのため、深さの境界付近ではサイト内の異なる分岐が異なる程度まで探索されることがあり、特に `maxDiscoveryDepth` の値が大きい場合に顕著です。より決定的な結果を得るには、`maxConcurrency` を `1` に設定するか、サイトに包括的なサイトマップがある場合は `sitemap: "only"` を使用してください。
> Firecrawl API キーが必要な AI エージェントですか？ 自動オンボーディング手順については、[firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) を参照してください。