Interact | Firecrawl

ページをスクレイピングしてクリーンなデータを取得し、その後 /interact を呼び出して、そのページ上でアクションを開始します: ボタンのクリック、フォームへの入力、動的コンテンツの抽出、さらに深いページへの移動が可能です。やりたいことを記述するだけでもよく、完全に制御したい場合はコードを書くこともできます。 Interact は次のような場合に使用します:

ログインが必要なページをスクレイピング — 一度サインインすれば、authentication 後にのみ表示されるページを読み取れます。Scrape + Interact での永続プロファイルを参照してください。
Pagination をクリックして進む — ページを送りながら各結果セットを取得し、1つのセッションを使い回します。プロンプトで操作するとセッションのライフサイクルを参照してください。
フォームの入力と送信 — prompt から、または Playwright のコードから、フィールドに入力して送信します。プロンプトで操作するとコードの実行を参照してください。
authentication 済みのセッションを再利用 — ブラウザの状態を名前付きプロファイルに保存し、以降のスクレイピングで読み込みます。Scrape + Interact での永続プロファイルを参照してください。
スクレイピングを介さずにセッションを開始 — 直接操作できる独立したブラウザを開きます。Browser Sandbox を参照してください。

適切な操作モデルを選択

必要なこと	使用するもの	正規ドキュメント	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()) を使用します。

AIプロンプト

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

コード実行

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 では、セッションの停止時に変更が保存されます。

クイックスタート

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

from firecrawl import Firecrawl

app = Firecrawl(
  # 開始にAPIキーは不要です — より高いレート制限のために追加してください:
  # api_key="fc-YOUR-API-KEY",
)

# 1. Amazonのホームページをスクレイピング
result = app.scrape("https://www.amazon.com", formats=["markdown"])
scrape_id = result.metadata.scrape_id

# 2. インタラクト — 商品を検索して価格を取得
app.interact(scrape_id, prompt="Search for iPhone 16 Pro Max")
response = app.interact(scrape_id, prompt="Click on the first result and tell me the price")
print(response.output)

# 3. セッションを停止
app.stop_interaction(scrape_id)

import { Firecrawl } from 'firecrawl';

const app = new Firecrawl({
  // 開始にAPIキーは不要です — レート制限を引き上げるには追加してください:
  // apiKey: 'fc-YOUR-API-KEY',
});

// 1. Scrape Amazon's homepage
const result = await app.scrape('https://www.amazon.com', { formats: ['markdown'] });
const scrapeId = result.metadata?.scrapeId;

// 2. Interact — search for a product and get its price
await app.interact(scrapeId, { prompt: 'Search for iPhone 16 Pro Max' });
const response = await app.interact(scrapeId, { prompt: 'Click on the first result and tell me the price' });
console.log(response.output);

// 3. Stop the session
await app.stopInteraction(scrapeId);

# 1. Amazonのホームページをスクレイピングする
# 開始時にAPI keyは不要 — より高いレート制限を利用するには -H "Authorization: Bearer $FIRECRAWL_API_KEY" を追加してください:
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.amazon.com", "formats": ["markdown"]}')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

# 2. インタラクト — 商品を検索して価格を取得する
curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Search for iPhone 16 Pro Max"}'

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Click on the first result and tell me the price"}'

# 3. セッションを停止する
curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact"

# 1. AmazonのホームページをスクレイピングするスクレイピングIDは自動的に保存されます）
firecrawl scrape https://www.amazon.com

# 2. 操作する — 商品を検索して価格を取得する
firecrawl interact "Search for iPhone 16 Pro Max"
firecrawl interact "Click on the first result and tell me the price"

# 3. セッションを停止する
firecrawl interact stop

Response

{
  "success": true,
  "cdpUrl": "wss://browser.firecrawl.dev/...",
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "output": "The iPhone 16 Pro Max (256GB) is priced at $1,199.00.",
  "exitCode": 0,
  "killed": false
}

プロンプトで操作する

ページを操作する最も簡単な方法です。やりたいことを自然言語で記述するだけで、自動的にクリック、入力、スクロール、データの抽出を行います。

response = app.interact(scrape_id, prompt="What are the customer reviews saying about battery life?")
print(response.output)

const response = await app.interact(scrapeId, {
  prompt: 'What are the customer reviews saying about battery life?',
});
console.log(response.output);

# まずスクレイピングして scrapeId を取得します
# 開始するためにAPIキーは不要です — より高いrate limitsを利用するには -H "Authorization: Bearer $FIRECRAWL_API_KEY" を追加してください:
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.amazon.com", "formats": ["markdown"]}')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What are the customer reviews saying about battery life?"
  }'

firecrawl interact "What are the customer reviews saying about battery life?"

レスポンスには、エージェントの回答が含まれる output フィールドがあります。

Response

{
  "success": true,
  "cdpUrl": "wss://browser.firecrawl.dev/...",
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "output": "Customers are generally positive about battery life. Most reviewers report 8-10 hours of use on a single charge. A few noted it drains faster with heavy multitasking.",
  "stdout": "...",
  "result": "...",
  "stderr": "",
  "exitCode": 0,
  "killed": false
}

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

プロンプトは、それぞれが単一の明確なタスクであるときに最も効果を発揮します。エージェントに複雑な複数ステップのワークフローを一度に実行させるのではなく、個別の 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 はすでにブラウザに接続されています。

response = app.interact(scrape_id, code="""
// ボタンをクリックしてナビゲーションを待機
await page.click('#next-page');
await page.waitForLoadState('networkidle');

// 新しいページからコンテンツを取得
const title = await page.title();
const content = await page.$eval('.article-body', el => el.textContent);
JSON.stringify({ title, content });
""")
print(response.result)

const response = await app.interact(scrapeId, {
  code: `
    // ボタンをクリックしてナビゲーションを待機する
    await page.click('#next-page');
    await page.waitForLoadState('networkidle');

    // 新しいページからコンテンツを抽出する
    const title = await page.title();
    const content = await page.$eval('.article-body', el => el.textContent);
    JSON.stringify({ title, content });
  `,
});
console.log(response.result);

# まずスクレイピングして scrapeId を取得します
# 開始するためにAPI keyは不要です — より高いrate limitsを利用するには -H "Authorization: Bearer $FIRECRAWL_API_KEY" を追加してください:
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "formats": ["markdown"]}')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "await page.click(\"#next-page\"); await page.waitForLoadState(\"networkidle\"); const title = await page.title(); JSON.stringify({ title });",
    "language": "node",
    "timeout": 30
  }'

# 最後のスクレイピングを自動的に使用する
firecrawl interact -c "
  await page.click('#next-page');
  await page.waitForLoadState('networkidle');
  const title = await page.title();
  const content = await page.\$eval('.article-body', el => el.textContent);
  JSON.stringify({ title, content });
"

# またはスクレイピングIDを明示的に渡す
# firecrawl interact <scrape-id> -c "await page.title()"

Python

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

response = app.interact(
    scrape_id,
    code="""
import json

await page.click('#load-more')
await page.wait_for_load_state('networkidle')

items = await page.query_selector_all('.item')
data = []
for item in items:
    text = await item.text_content()
    data.append(text.strip())

print(json.dumps(data))
""",
    language="python",
)
print(response.stdout)

const response = await app.interact(scrapeId, {
  code: `
import json

await page.click('#load-more')
await page.wait_for_load_state('networkidle')

items = await page.query_selector_all('.item')
data = []
for item in items:
    text = await item.text_content()
    data.append(text.strip())

print(json.dumps(data))
`,
  language: 'python',
});
console.log(response.stdout);

# まずスクレイピングして scrapeId を取得します
# 開始にAPIキーは不要です — より高いrate limitsを利用するには -H "Authorization: Bearer $FIRECRAWL_API_KEY" を追加してください:
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "formats": ["markdown"]}')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import json\nawait page.click(\"#load-more\")\nawait page.wait_for_load_state(\"networkidle\")\nitems = await page.query_selector_all(\".item\")\ndata = [await i.text_content() for i in items]\nprint(json.dumps(data))",
    "language": "python"
  }'

firecrawl interact --python -c "
import json
await page.click('#load-more')
await page.wait_for_load_state('networkidle')
items = await page.query_selector_all('.item')
data = [await i.text_content() for i in items]
print(json.dumps(data))
"

Bash (agent-browser)

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

# インタラクティブな要素を確認するためにスナップショットを取得する
snapshot = app.interact(
    scrape_id,
    code="agent-browser snapshot -i",
    language="bash",
)
print(snapshot.stdout)
# 出力:
# [document]
#   @e1 [input type="text"] "Search..."
#   @e2 [button] "Search"
#   @e3 [link] "About"

# @refs を使用して要素を操作する
app.interact(
    scrape_id,
    code='agent-browser fill @e1 "firecrawl" && agent-browser click @e2',
    language="bash",
)

// インタラクティブな要素を確認するためにスナップショットを取得する
const snapshot = await app.interact(scrapeId, {
  code: 'agent-browser snapshot -i',
  language: 'bash',
});
console.log(snapshot.stdout);
// Output:
// [document]
//   @e1 [input type="text"] "Search..."
//   @e2 [button] "Search"
//   @e3 [link] "About"

// @refs を使用して要素を操作する
await app.interact(scrapeId, {
  code: 'agent-browser fill @e1 "firecrawl" && agent-browser click @e2',
  language: 'bash',
});

# まずスクレイピングして scrapeId を取得する
# 開始するにはAPIキーは不要です — より高いレート制限を利用するには -H "Authorization: Bearer $FIRECRAWL_API_KEY" を追加してください:
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "formats": ["markdown"]}')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

# インタラクティブな要素を確認するためにスナップショットを取得する
curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"code": "agent-browser snapshot -i", "language": "bash"}'

# Interact with elements using @refs
curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"code": "agent-browser fill @e1 \"firecrawl\" && agent-browser click @e2", "language": "bash"}'

# インタラクティブな要素を確認するためにスナップショットを取得する
firecrawl interact --bash -c "agent-browser snapshot -i"

# @refs を使用して要素を操作する
firecrawl interact --bash -c 'agent-browser fill @e1 "firecrawl" && agent-browser click @e2'

一般的な 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 の構築に便利です。

Response

{
  "success": true,
  "cdpUrl": "wss://browser.firecrawl.dev/...",
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "stdout": "",
  "result": "...",
  "exitCode": 0
}

<iframe src="LIVE_VIEW_URL" width="100%" height="600" />

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

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

<iframe src="INTERACTIVE_LIVE_VIEW_URL" width="100%" height="600" />

CDP URL

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

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP(cdpUrl);
const context = browser.contexts()[0];
const page = context.pages()[0];

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

作成

最初の POST /v2/scrape/{scrapeId}/interact 呼び出しで、スクレイピングセッションが継続され、インタラクションが開始されます。

再利用

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

# 最初の呼び出し: タブをクリック
app.interact(scrape_id, code="await page.click('#tab-2')")

# 2回目の呼び出し: タブは引き続き選択されたままで、その内容を抽出
result = app.interact(scrape_id, code="await page.$eval('#tab-2-content', el => el.textContent)")
print(result.result)

// 最初の呼び出し: タブをクリック
await app.interact(scrapeId, { code: "await page.click('#tab-2')" });

// 2回目の呼び出し: タブは引き続き選択されたままで、その内容を抽出
const result = await app.interact(scrapeId, {
  code: "await page.$eval('#tab-2-content', el => el.textContent)",
});
console.log(result.result);

# 最初の呼び出し: タブをクリック
firecrawl interact -c "await page.click('#tab-2')"

# 2回目の呼び出し: タブは引き続き選択されたままで、その内容を抽出
firecrawl interact -c "await page.\$eval('#tab-2-content', el => el.textContent)"

クリーンアップ

使用が終わったら、明示的にセッションを停止してください:

app.stop_interaction(scrape_id)

await app.stopInteraction(scrapeId);

# SCRAPE_ID は、先に実行した POST /v2/scrape の呼び出しで返された scrapeId です。
# 例: SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')
# 開始にAPI keyは不要です — より高いrate limitsを利用するには -H "Authorization: Bearer $FIRECRAWL_API_KEY" を追加してください:
curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact"

# 最後のスクレイピングセッションを停止する
firecrawl interact stop

# またはIDで特定のセッションを停止する
# firecrawl interact stop <scrape-id>

セッションは、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

curl -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown"],
    "profile": {
      "name": "my-profile",
      "saveChanges": true
    }
  }'

curl -X POST "https://api.firecrawl.dev/v2/scrape/SCRAPE_ID/interact" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Click the login button"
  }'

curl -X DELETE "https://api.firecrawl.dev/v2/scrape/SCRAPE_ID/interact" \
  -H "Authorization: Bearer fc-YOUR_API_KEY"

プロファイルのライフサイクルは次のとおりです。

profile.name と saveChanges: true を指定してスクレイピングを作成します。
返された scrapeId に対して、プロンプトまたはコードで操作を実行します。
セッションを停止して、cookies、localStorage、その他のブラウザの状態を保存します。
後続のスクレイピングを同じ profile.name で開始します。変更を書き戻さずに既存の状態だけを読み取りたい場合は、saveChanges: false を使用します。

from firecrawl import Firecrawl

app = Firecrawl(
  # 開始にAPI keyは不要です — より高いレート制限のために追加してください:
  # api_key="fc-YOUR-API-KEY",
)

# セッション1: プロファイルでスクレイピングし、ログインして停止（状態は保存される）
result = app.scrape(
    "https://app.example.com/login",
    formats=["markdown"],
    profile={"name": "my-app", "save_changes": True},
)
scrape_id = result.metadata.scrape_id

app.interact(scrape_id, prompt="Fill in user@example.com and password, then click Login")
app.stop_interaction(scrape_id)

# セッション2: 同じプロファイルで読み取り専用モードでスクレイピング — すでにログイン済み
result = app.scrape(
    "https://app.example.com/dashboard",
    formats=["markdown"],
    profile={"name": "my-app", "save_changes": False},
)
scrape_id = result.metadata.scrape_id

response = app.interact(scrape_id, prompt="Extract the dashboard data")
print(response.output)
app.stop_interaction(scrape_id)

import { Firecrawl } from 'firecrawl';

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

// Session 1: Scrape with a profile, log in, then stop (state is saved)
const result1 = await app.scrape('https://app.example.com/login', {
  formats: ['markdown'],
  profile: { name: 'my-app', saveChanges: true },
});
const scrapeId1 = result1.metadata?.scrapeId;

await app.interact(scrapeId1, { prompt: 'Fill in user@example.com and password, then click Login' });
await app.stopInteraction(scrapeId1);

// セッション2: 同じプロファイルで読み取り専用モードでスクレイピング — すでにログイン済み
const result2 = await app.scrape('https://app.example.com/dashboard', {
  formats: ['markdown'],
  profile: { name: 'my-app', saveChanges: false },
});
const scrapeId2 = result2.metadata?.scrapeId;

const response = await app.interact(scrapeId2, { prompt: 'Extract the dashboard data' });
console.log(response.output);
await app.stopInteraction(scrapeId2);

# Session 1: Scrape with a profile
# 開始にAPI キーは不要 — より高いレート制限を利用するには -H "Authorization: Bearer $FIRECRAWL_API_KEY" を追加してください:
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/login",
    "formats": ["markdown"],
    "profile": { "name": "my-app", "saveChanges": true }
  }')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

# Log in via interact
curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Fill in user@example.com and password, then click Login"}'

# 停止 — 状態はプロファイルに保存される
curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact"

# セッション2: 読み取り専用モードで同じプロファイルを使用して再度スクレイピング — すでにログイン済み
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/dashboard",
    "formats": ["markdown"],
    "profile": { "name": "my-app", "saveChanges": false }
  }')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Extract the dashboard data"}'

# セッション1: プロファイルでスクレイピングし、ログインして停止する（状態は保存される）
firecrawl scrape https://app.example.com/login --profile my-app
firecrawl interact "Fill in user@example.com and password, then click Login"
firecrawl interact stop

# セッション2: 同じプロファイルでスクレイピング — すでにログイン済み
firecrawl scrape https://app.example.com/dashboard --profile my-app
firecrawl interact "Extract the dashboard data"
firecrawl interact stop

# 読み取り専用: 変更を保存せずにプロファイルの状態を読み込む
firecrawl scrape https://app.example.com/dashboard --profile my-app --no-save-changes

パラメータ	デフォルト	説明
`name`	None	永続プロファイルの名前です。同じ名前のスクレイピングはブラウザの状態を共有します。
`saveChanges`	`true`	`true` の場合、interact セッションの停止時にブラウザの状態がプロファイルに保存されます。既存のデータを読み込み、変更を書き戻さないようにするには、`false` に設定します。これは、複数の同時リーダーが必要な場合に便利です。

一度にプロファイルへ保存できるセッションは 1 つだけです。別のセッションがすでに保存中の場合は、409 エラーが返されます。saveChanges: false で同じプロファイルを開くことはできますし、後でもう一度試すこともできます。

ブラウザの状態は、interact セッションが停止したときに保存されます。プロファイルを再利用できるよう、完了したら必ずセッションを停止してください。

永続化の検証

実際のログインフローに頼らずに永続化をテストするには、1つ目のセッションで localStorage に値を書き込み、そのセッションを停止したあと、同じプロファイルを使う2つ目のセッションでその値を読み取ります。

cURL

# セッション1: ブラウザの状態を書き込んで保存する
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown"],
    "profile": { "name": "profile-validation", "saveChanges": true }
  }')

SCRAPE_ID=$(echo "$RESPONSE" | jq -r ".data.metadata.scrapeId")

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "await page.evaluate(() => { localStorage.setItem(\"firecrawlProfileCheck\", \"saved\"); document.cookie = \"firecrawl_profile_check=saved; path=/; max-age=3600\"; return localStorage.getItem(\"firecrawlProfileCheck\"); });"
  }'

curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

# セッション2: 同じプロファイルを読み取り専用モードで読み込み、値を検証する
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown"],
    "profile": { "name": "profile-validation", "saveChanges": false }
  }')

SCRAPE_ID=$(echo "$RESPONSE" | jq -r ".data.metadata.scrapeId")

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "await page.evaluate(() => ({ localStorage: localStorage.getItem(\"firecrawlProfileCheck\"), cookie: document.cookie.includes(\"firecrawl_profile_check=saved\") }));"
  }'

curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

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 でお問い合わせください。

はじめに

主要エンドポイント

その他

クイックスタート

開発者ガイド

webhook

ユースケース

その他

貢献

スクレイピング後にページをInteract

適切な操作モデルを選択

AIプロンプト

コード実行

ライブビュー

動作の仕組み

クイックスタート

プロンプトで操作する

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

コードの実行

Node.js (Playwright)

Python

Bash (agent-browser)

ライブビュー

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

CDP URL

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

作成

再利用

クリーンアップ

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

永続化の検証

使い分けの目安

料金

API リファレンス

リクエスト本文 (POST)

レスポンス

​適切な操作モデルを選択

AIプロンプト

コード実行

ライブビュー

​動作の仕組み

​クイックスタート

​プロンプトで操作する

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

​コードの実行

​Node.js (Playwright)

​Python

​Bash (agent-browser)

​ライブビュー

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

​CDP URL

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

​作成

​再利用

​クリーンアップ

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

​永続化の検証

​使い分けの目安

​料金

​API リファレンス

​リクエスト本文 (POST)

​レスポンス

適切な操作モデルを選択

動作の仕組み

クイックスタート

プロンプトで操作する

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

コードの実行

Node.js (Playwright)

Python

Bash (agent-browser)

ライブビュー

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

CDP URL

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

作成

再利用

クリーンアップ

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

永続化の検証

使い分けの目安

料金

API リファレンス

リクエスト本文 (POST)

レスポンス