ページをスクレイピングしてクリーンなデータを取得し、その後 /interact を呼び出して、そのページ上でアクションを開始します: ボタンのクリック、フォームへの入力、動的コンテンツの抽出、さらに深いページへの移動が可能です。やりたいことを記述するだけでもよく、完全に制御したい場合はコードを書くこともできます。
対象となるには、Firecrawl Feedback Assistant との内容の濃いインタビュー (よく考えられた具体的なユースケースなど) を完了してください。所要時間は数分で、いつでも中断できます。人間にもエージェントにも対応しており (リンクをエージェント用ハーネスに貼り付けるだけです!) 、/interact を使ったことがない場合でも、ご意見をお聞かせください。
インタビューを開始
報奨金の対象となるには、メールアドレスを入力してください。インタビューは毎週末に品質を確認します。
適切な操作モデルを選択#
| 必要なこと | 使用するもの | 正規ドキュメント | SDK メソッド (Node) |
|---|---|---|---|
| 最初にスクレイピングせず、独立したブラウザセッションを開始する | Browser Sandbox / 独立した Interact セッション | Browser Sandbox, Create Browser Session, Execute Browser Code, List Browser Sessions, Delete Browser Session | browser(), browserExecute(), listBrowsers(), deleteBrowser() |
scrapeId を使ってスクレイピング結果から続行する | スクレイピング後に Interact | Execute Interact, Stop Interact | interact(), stopInteraction() |
ワークフローが POST /v2/scrape で始まり、レスポンスに data.metadata.scrapeId が含まれる場合は、スクレイピングに紐づいた Interact を使用します。独自のライフサイクルを持つ独立したセッションが必要な場合は、Browser Sandbox を使用します。Python SDK では、snake_case の同等メソッド (browser(), browser_execute(), list_browsers(), delete_browser(), interact(), stop_interaction()) を使用します。
ページ上で実行したいアクションを記述します
Playwright や agent-browser を使って、安全にコード実行で操作できます
埋め込み可能なストリームを通じて、ブラウザーをリアルタイムで確認したり操作したりできます
動作の仕組み#
POST /v2/scrapeで URL をスクレイピングします。レスポンスにはdata.metadata.scrapeIdにscrapeIdが含まれます。ブラウザの状態を保持したい場合は、このリクエストでprofileを渡します。promptまたは Playwright のcodeを指定してPOST /v2/scrape/{scrapeId}/interactを呼び出し、Interactします。ここではprofileを渡さないでください。Interact セッションはスクレイピングジョブからprofileを引き継ぎます。- 完了したら、
DELETE /v2/scrape/{scrapeId}/interactでセッションを停止します。書き込み可能なprofileでは、セッションの停止時に変更が保存されます。
クイックスタート#
ページをスクレイピングし、操作し、セッションを停止します:
プロンプトで操作する#
ページを操作する最も簡単な方法です。やりたいことを自然言語で記述するだけで、自動的にクリック、入力、スクロール、データの抽出を行います。
レスポンスには、エージェントの回答が含まれる output フィールドがあります。
プロンプトは小さく、焦点を絞る#
プロンプトは、それぞれが単一の明確なタスクであるときに最も効果を発揮します。エージェントに複雑な複数ステップのワークフローを一度に実行させるのではなく、個別の 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 コマンド:
| コマンド | 説明 |
|---|---|
snapshot | 要素参照付きの完全なアクセシビリティツリー |
snapshot -i | インタラクティブな要素のみ |
click @e1 | 参照で要素をクリック |
fill @e1 "text" | フィールドをクリアしてテキストを入力 |
type @e1 "text" | クリアせずにテキストを入力 |
press Enter | キーボードのキーを押す |
scroll down 500 | 500 ピクセル下にスクロール |
get text @e1 | テキストコンテンツを取得 |
get url | 現在の URL を取得 |
wait @e1 | 要素が表示されるまで待機 |
wait --load networkidle | ネットワークがアイドル状態になるまで待機 |
find text "X" click | テキストで要素を見つけてクリック |
screenshot | 現在のページのスクリーンショットを撮る |
eval "js code" | ページ内で JavaScript を実行 |
ライブビュー#
すべての Interact レスポンスでは、埋め込んでブラウザをリアルタイムで確認できる liveViewUrl が返されます。デバッグやデモ、ブラウザ駆動の UI の構築に便利です。
インタラクティブ ライブビュー#
レスポンスには interactiveLiveViewUrl も含まれます。閲覧専用の標準ライブビューとは異なり、インタラクティブ ライブビューでは、埋め込みストリームを通じてユーザーがブラウザセッションを直接クリック、入力、操作できます。これは、ログインフローや、エンドユーザーがブラウザを操作する必要があるガイド付きワークフローなど、ユーザー向けのブラウザUIを構築する場合に役立ちます。
CDP URL#
すべてのInteractレスポンスでは、cdpUrl も返されます。これは、ブラウザセッション用の生の Chrome DevTools Protocol (CDP) WebSocket URL です。これを使うと、Playwright、Puppeteer、または任意のCDPクライアントからライブセッションに直接接続し、自分のコードでブラウザを操作できます。
セッションのライフサイクル#
作成#
最初の POST /v2/scrape/{scrapeId}/interact 呼び出しで、スクレイピングセッションが継続され、インタラクションが開始されます。
再利用#
同じ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 セッションを停止してください。
プロファイルのライフサイクルは次のとおりです。
profile.nameとsaveChanges: trueを指定してスクレイピングを作成します。- 返された
scrapeIdに対して、プロンプトまたはコードで操作を実行します。 - セッションを停止して、cookies、localStorage、その他のブラウザの状態を保存します。
- 後続のスクレイピングを同じ
profile.nameで開始します。変更を書き戻さずに既存の状態だけを読み取りたい場合は、saveChanges: falseを使用します。
| パラメータ | デフォルト | 説明 |
|---|---|---|
name | None | 永続プロファイルの名前です。同じ名前のスクレイピングはブラウザの状態を共有します。 |
saveChanges | true | true の場合、interact セッションの停止時にブラウザの状態がプロファイルに保存されます。既存のデータを読み込み、変更を書き戻さないようにするには、false に設定します。これは、複数の同時リーダーが必要な場合に便利です。 |
一度にプロファイルへ保存できるセッションは 1 つだけです。別のセッションがすでに保存中の場合は、409 エラーが返されます。saveChanges: false で同じプロファイルを開くことはできますし、後でもう一度試すこともできます。
ブラウザの状態は、interact セッションが停止したときに保存されます。プロファイルを再利用できるよう、完了したら必ずセッションを停止してください。
永続化の検証#
実際のログインフローに頼らずに永続化をテストするには、1つ目のセッションで localStorage に値を書き込み、そのセッションを停止したあと、同じプロファイルを使う2つ目のセッションでその値を読み取ります。
2回目のInteractレスポンスでは、localStorage が "saved"、cookie が true と表示されるはずです。
API 経由で作成したプロファイルは、まだ Dashboard > Interact > Profiles に表示されない場合があります。現在、Dashboard では API で作成された永続プロファイルの完全な一覧は確認できません。
使い分けの目安#
| ユースケース | 推奨 | 理由 |
|---|---|---|
| Web search | Search | 専用の検索エンドポイント |
| URL から整形されたコンテンツを取得 | Scrape | API 呼び出し 1 回で、セッション不要 |
| ページ上でクリック、入力、移動を行う | Interact (prompt) | 英語で指示するだけ |
| 操作の先にあるデータを抽出する | Interact (prompt) | セレクタ不要 |
| 複雑なスクレイピングロジック | Interact (code) | Playwright を完全に制御可能 |
Interact と Browser Sandbox の違い: Interact は Browser Sandbox と同じインフラ上に構築されていますが、最も一般的なパターン、つまりページをスクレイピングしてからさらに深く進む場合に、より使いやすいインターフェースを提供します。Browser Sandbox は、特定のスクレイピングに紐づかない独立したブラウザセッションが必要な場合に適しています。
料金#
- コードのみ (
promptなし): セッション1分あたり2 credits - AI プロンプト あり: セッション1分あたり7 credits
- スクレイピング: スクレイピング自体の請求は別途行われます (スクレイピング1回あたり1 credit に加え、format ごとのコスト) 。
API リファレンス#
- Execute Interact:
POST /v2/scrape/{scrapeId}/interact - Stop Interact:
DELETE /v2/scrape/{scrapeId}/interact
リクエスト本文 (POST)#
| フィールド | 型 | デフォルト | 説明 |
|---|---|---|---|
prompt | string | なし | AIエージェント向けの自然言語タスクです。code が設定されていない場合は必須です。最大10,000文字。 |
code | string | なし | 実行するコード (Node.js、Python、または Bash) 。prompt が設定されていない場合は必須です。最大100,000文字。 |
language | string | "node" | "node"、"python"、または "bash"。code を使用する場合にのみ指定します。 |
timeout | number | 30 | タイムアウト時間 (秒) (1~300) 。 |
origin | string | なし | アクティビティ追跡用の呼び出し元識別子。 |
レスポンス#
| Field | Description |
|---|---|
success | エラーなく実行が完了した場合は true |
cdpUrl | ブラウザセッション用の生の Chrome DevTools Protocol (CDP) WebSocket URL。Playwright、Puppeteer、または任意の CDP クライアントで直接接続できます |
liveViewUrl | ブラウザセッション用の読み取り専用のライブビュー URL |
interactiveLiveViewUrl | インタラクティブ ライブビュー URL (閲覧者がブラウザを操作できます) |
output | プロンプトに対するエージェントの自然言語での回答。prompt を使用している場合にのみ含まれます。 |
stdout | コード実行時の標準出力 |
result | サンドボックスからの生の戻り値。code の場合: 最後に評価された式。prompt の場合: エージェントが output の生成に使用した生のページスナップショット。 |
stderr | 標準エラー出力 |
exitCode | 終了コード (0 = 成功) |
killed | タイムアウトにより実行が終了した場合は true |
フィードバックやサポートが必要な場合は、help@firecrawl.com にメールするか、Discord でお問い合わせください。

