Skip to main content
ページをスクレイピングしてクリーンなデータを取得し、その後 /interact を呼び出して、そのページ上でアクションを開始します: ボタンのクリック、フォームへの入力、動的コンテンツの抽出、さらに深いページへの移動が可能です。やりたいことを記述するだけでもよく、完全に制御したい場合はコードを書くこともできます。 Interact は次のような場合に使用します:
  • ログインが必要なページをスクレイピング — 一度サインインすれば、authentication 後にのみ表示されるページを読み取れます。Scrape + Interact での永続プロファイル を参照してください。
  • Pagination をクリックして進む — ページを送りながら各結果セットを取得し、1つの セッション を使い回します。プロンプトで操作する と セッションのライフサイクル を参照してください。
  • フォームの入力と送信 — prompt から、または Playwright のコードから、フィールドに入力して送信します。プロンプトで操作する と コードの実行 を参照してください。
  • authentication 済みの セッション を再利用 — ブラウザの状態を名前付きプロファイルに保存し、以降のスクレイピングで読み込みます。Scrape + Interact での永続プロファイル を参照してください。
  • スクレイピングを介さずに セッション を開始 — 直接操作できる独立したブラウザを開きます。Browser Sandbox を参照してください。

適切な操作モデルを選択

ワークフローが POST /v2/scrape で始まり、レスポンスに data.metadata.scrapeId が含まれる場合は、スクレイピングに紐づいた Interact を使用します。独自のライフサイクルを持つ独立したセッションが必要な場合は、Browser Sandbox を使用します。Python SDK では、snake_case の同等メソッド (browser(), browser_execute(), list_browsers(), delete_browser(), interact(), stop_interaction()) を使用します。

AIプロンプト

ページ上で実行したいアクションを記述します

コード実行

Playwright や agent-browser を使って、安全にコード実行で操作できます

ライブビュー

埋め込み可能なストリームを通じて、ブラウザーをリアルタイムで確認したり操作したりできます

動作の仕組み

  1. POST /v2/scrape で URL をスクレイピングします。レスポンスには data.metadata.scrapeId に scrapeId が含まれます。ブラウザの状態を保持したい場合は、このリクエストで profile を渡します。
  2. prompt または Playwright の code を指定して POST /v2/scrape/{scrapeId}/interact を呼び出し、Interactします。ここでは profile を渡さないでください。Interact セッションはスクレイピングジョブから profile を引き継ぎます。
  3. 完了したら、DELETE /v2/scrape/{scrapeId}/interact でセッションを停止します。書き込み可能な profile では、セッションの停止時に変更が保存されます。

クイックスタート

ページをスクレイピングし、操作し、セッションを停止します:
Response

プロンプトで操作する

ページを操作する最も簡単な方法です。やりたいことを自然言語で記述するだけで、自動的にクリック、入力、スクロール、データの抽出を行います。
レスポンスには、エージェントの回答が含まれる output フィールドがあります。
Response

プロンプトは小さく、焦点を絞る

プロンプトは、それぞれが単一の明確なタスクであるときに最も効果を発揮します。エージェントに複雑な複数ステップのワークフローを一度に実行させるのではなく、個別の interact 呼び出しに分けてください。各呼び出しは同じブラウザセッションを再利用するため、それまでの状態が引き継がれます。

コードの実行

より細かく制御したい場合は、ブラウザサンドボックスでコードを直接実行できます。page 変数 (Playwright の Page オブジェクト) は Node.js と Python で利用できます。Bash モードには agent-browser がプリインストールされています。セッション内でスクリーンショットを撮ることもできます: Node.js では (await page.screenshot()).toString("base64")、Python では await page.screenshot(path="/tmp/screenshot.png")、Bash では agent-browser screenshot を使用してください。

Node.js (Playwright)

デフォルトの言語です。Playwright のコードを直接記述できます。page はすでにブラウザに接続されています。

Python

Playwright の Python API を使う場合は、language を "python" に設定します。

Bash (agent-browser)

agent-browser は、60 以上のコマンドがプリインストールされたサンドボックス内の CLI です。要素参照 (@e1, @e2, …) 付きのアクセシビリティツリーを提供し、LLM による自動化に最適です。
一般的な agent-browser コマンド:

ライブビュー

すべての Interact レスポンスでは、埋め込んでブラウザをリアルタイムで確認できる liveViewUrl が返されます。デバッグやデモ、ブラウザ駆動の UI の構築に便利です。
Response

インタラクティブ ライブビュー

レスポンスには interactiveLiveViewUrl も含まれます。閲覧専用の標準ライブビューとは異なり、インタラクティブ ライブビューでは、埋め込みストリームを通じてユーザーがブラウザセッションを直接クリック、入力、操作できます。これは、ログインフローや、エンドユーザーがブラウザを操作する必要があるガイド付きワークフローなど、ユーザー向けのブラウザUIを構築する場合に役立ちます。

CDP URL

すべてのInteractレスポンスでは、cdpUrl も返されます。これは、ブラウザセッション用の生の Chrome DevTools Protocol (CDP) WebSocket URL です。これを使うと、Playwright、Puppeteer、または任意のCDPクライアントからライブセッションに直接接続し、自分のコードでブラウザを操作できます。

セッションのライフサイクル

作成

最初の POST /v2/scrape/{scrapeId}/interact 呼び出しで、スクレイピングセッションが継続され、操作が開始されます。 セッションは、スクレイピングと同じ国からブラウジングします。スクレイピングで指定した location.country が使用され、国が指定されていない場合は米国が使用されます。interact には location を渡さず、POST /v2/scrape リクエスト側で設定してください。

再利用

同じscrapeIdに対する後続のinteract呼び出しでは、既存のセッションが再利用されます。browserは開いたままで、呼び出し間でも状態が維持されるため、複数のインタラクションを連続して実行できます。

クリーンアップ

使用が終わったら、明示的にセッションを停止してください:
セッションは、TTL (default: 10分) または非アクティブ タイムアウト (default: 5分) に基づいて自動的に期限切れになります。
不要な課金を避けるため、使用後は必ずセッションを停止してください。Credits は秒単位で按分されます。最低料金はブラウザ1分です。prompt を使用するセッションはブラウザ1分あたり7 Credits、prompt を使用しないセッションは2 Credits が課金されます。詳細は課金を参照してください。

Scrape + Interact での永続プロファイル

デフォルトでは、各スクレイピング + interact セッションはクリーンなブラウザで開始されます。profile を使うと、スクレイピング間でブラウザの状態 (cookies、localStorage、sessions) を保存して再利用できます。これは、ログイン状態を維持したり、設定を保持したりするのに便利です。 最初の POST /v2/scrape リクエストに profile オブジェクトを渡します。POST /v2/scrape/{scrapeId}/interact には profile を渡さないでください。interact セッションは、scrape ジョブのブラウザセッションとプロファイル設定を再利用します。書き込み可能なプロファイルの変更を保存できるように、DELETE /v2/scrape/{scrapeId}/interact で interact セッションを停止してください。
cURL
プロファイルのライフサイクルは次のとおりです。
  1. profile.name と saveChanges: true を指定してスクレイピングを作成します。
  2. 返された scrapeId に対して、プロンプトまたはコードで操作を実行します。
  3. セッションを停止して、cookies、localStorage、その他のブラウザの状態を保存します。
  4. 後続のスクレイピングを同じ profile.name で開始します。変更を書き戻さずに既存の状態だけを読み取りたい場合は、saveChanges: false を使用します。
一度にプロファイルへ保存できるセッションは 1 つだけです。別のセッションがすでに保存中の場合は、409 エラーが返されます。saveChanges: false で同じプロファイルを開くことはできますし、後でもう一度試すこともできます。
ブラウザの状態は、interact セッションが停止したときに保存されます。プロファイルを再利用できるよう、完了したら必ずセッションを停止してください。

永続化の検証

実際のログインフローに頼らずに永続化をテストするには、1つ目のセッションで localStorage に値を書き込み、そのセッションを停止したあと、同じプロファイルを使う2つ目のセッションでその値を読み取ります。
cURL
2回目のInteractレスポンスでは、localStorage が "saved"、cookie が true と表示されるはずです。
API 経由で作成したプロファイルは、まだ Dashboard > Interact > Profiles に表示されない場合があります。現在、Dashboard では API で作成された永続プロファイルの完全な一覧は確認できません。

データ保持ゼロ (ZDR)

Interact は、厳格なデータ取り扱い要件があるTeam向けにデータ保持ゼロ (ZDR) をサポートしています。有効にすると、Firecrawl はページのコンテンツや実行の出力を、セッション終了後に永続化しません。 ZDR を有効にするには、最初の interact 呼び出しで zeroDataRetention: true を設定します。
cURL
POST /v2/interact でスタンドアロンのセッションを作成する際にも、zeroDataRetention: true を指定できます。zeroDataRetention: true を指定して実行したスクレイピングに対して Interact を行うと、ZDR セッションが自動的に開始されます。保持ポリシーはセッション単位で保存されるため、同じセッションへの以降の呼び出しでは、このオプションを省略しても ZDR モードが維持されます。 ZDR はエンタープライズプランで利用でき、Teamで有効化されている必要があります。ZDR が有効化されていないTeamから zeroDataRetention: true を指定してリクエストを送信すると、403 が返されます。利用を開始するには firecrawl.dev/enterprise にアクセスしてください。
  • ZDR モードでは、セッションの録画と永続化されたプロファイルは利用できません。zeroDataRetention: true を recordSession または profile と併用したリクエストには 400 が返されます。
  • ZDR なしで開始した既存のセッションを ZDR に切り替えることはできません。そのセッションで ZDR を指定すると 409 が返されます。セッションを停止し、zeroDataRetention: true を指定して新しいセッションを開始してください。
  • ZDR のスクレイピングではスクレイピング対象の URL が保持されないため、Firecrawl が元のスクレイピングからブラウザーを再構築できない場合があります。リプレイコンテキストを利用できない旨の 409 が Interact から返された場合は、リクエストに url を指定すると、新しい ZDR セッションでそのページを開けます。なお、元のスクレイピングのアクションは再実行されません。
ZDR セッションのコストについては、料金を参照してください。

使い分けの目安

Interact と Browser Sandbox の違い: Interact は Browser Sandbox と同じインフラ上に構築されていますが、最も一般的なパターン、つまりページをスクレイピングしてからさらに深く進む場合に、より使いやすいインターフェースを提供します。Browser Sandbox は、特定のスクレイピングに紐づかない独立したブラウザセッションが必要な場合に適しています。

料金

  • コードのみ (prompt なし): セッション1分あたり2 credits
  • AI プロンプト あり: セッション1分あたり7 credits
  • スクレイピング: スクレイピング自体の請求は別途行われます (スクレイピング1回あたり1 credit に加え、format ごとのコスト) 。
  • データ保持ゼロ: ZDR セッションではセッション1分あたり2 credits が追加されます。そのため、コードのみのセッションは1分あたり4 credits、AI プロンプトありのセッションは1分あたり9 credits で課金されます (最低課金時間は同じく1分) 。ZDR スクレイピングには、これとは別に ZDR コスト として1ページあたり1 credit が追加でかかります。

API リファレンス

リクエスト本文 (POST)

レスポンス


フィードバックやサポートが必要な場合は、help@firecrawl.com にメールするか、Discord でお問い合わせください。