与已抓取的页面交互

与抓取任务关联的浏览器会话进行交互

curl --request POST \
  --url https://api.firecrawl.dev/v2/scrape/{jobId}/interact \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "<string>",
  "language": "node",
  "origin": "<string>",
  "timeout": 30
}
'

{
  "cdpUrl": "<string>",
  "error": "<string>",
  "exitCode": 123,
  "interactiveLiveViewUrl": "<string>",
  "killed": true,
  "liveViewUrl": "<string>",
  "output": "<string>",
  "result": "<string>",
  "stderr": "<string>",
  "stdout": "<string>",
  "success": true
}

POST

scrape

{jobId}

interact

与抓取任务关联的浏览器会话进行交互

curl --request POST \
  --url https://api.firecrawl.dev/v2/scrape/{jobId}/interact \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "<string>",
  "language": "node",
  "origin": "<string>",
  "timeout": 30
}
'

{
  "cdpUrl": "<string>",
  "error": "<string>",
  "exitCode": 123,
  "interactiveLiveViewUrl": "<string>",
  "killed": true,
  "liveViewUrl": "<string>",
  "output": "<string>",
  "result": "<string>",
  "stderr": "<string>",
  "stdout": "<string>",
  "success": true
}

使用此端点可继续与由先前抓取初始化的同一浏览器状态进行交互。必须提供 code 或 prompt 之一，不能同时提供两者。 POST /v2/scrape/{jobId}/interact 负责整个生命周期：

如果此抓取任务尚未存在浏览器会话，Firecrawl 会在与原始抓取相同的页面状态下创建一个会话。
提供 code 时，Firecrawl 会在浏览器沙箱中运行它；提供 prompt 时，AI 代理会使用自然语言自动完成该任务。
后续在同一 jobId 上调用 POST /interact 时，会复用同一个实时浏览器状态。

完成后，调用 DELETE /v2/scrape/{jobId}/interact 以停止该会话。

路径参数

参数	类型	必填	描述
`jobId`	string (UUID)	是	抓取响应中的 `data.metadata.scrapeId` 对应的抓取任务 ID

请求体

参数	类型	必填	默认值	描述
`code`	string	否	—	在浏览器沙箱中执行的代码 (1–100,000 个字符) 。如果未设置 `prompt`，则为必填。
`prompt`	string	否	—	提供给 AI 代理的自然语言任务 (1–10,000 个字符) 。如果未设置 `code`，则为必填。
`language`	string	否	`"node"`	`"python"`、`"node"` 或 `"bash"` 之一。仅在使用 `code` 时生效。
`timeout`	number	否	`30`	执行超时时间 (秒) (1–300) 。
`origin`	string	否	—	用于遥测的可选来源标识。

响应

字段	类型	描述
`success`	boolean	执行是否在无错误的情况下完成
`cdpUrl`	string	浏览器会话的原始 Chrome DevTools Protocol (CDP) WebSocket URL。可通过 Playwright、Puppeteer 或任何 CDP 客户端直接连接
`liveViewUrl`	string	浏览器会话的只读实时视图 URL
`interactiveLiveViewUrl`	string	交互式实时视图 URL (查看者可控制浏览器)
`output`	string	AI 代理的最终响应 (仅在使用 `prompt` 时返回)
`stdout`	string	代码执行的标准输出
`result`	string	返回值——对 Node.js 而言是最后一个表达式的值，对 `prompt` 而言是最终页面快照
`stderr`	string	标准错误输出
`exitCode`	number	执行退出码 (`0` = 成功)
`killed`	boolean	执行是否因超时而终止
`error`	string	错误信息 (仅在失败时返回)

示例请求 (代码)

curl -X POST "https://api.firecrawl.dev/v2/scrape/550e8400-e29b-41d4-a716-446655440000/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "const title = await page.title(); JSON.stringify({ title });",
    "language": "node",
    "timeout": 30
  }'

示例响应 (代码)

{
  "success": true,
  "cdpUrl": "wss://browser.firecrawl.dev/...",
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "stdout": "",
  "result": "{\"title\":\"Example Domain\"}",
  "stderr": "",
  "exitCode": 0,
  "killed": false
}

示例请求 (Prompt)

curl -X POST "https://api.firecrawl.dev/v2/scrape/550e8400-e29b-41d4-a716-446655440000/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Find the pricing section and tell me the price of the Pro plan",
    "timeout": 60
  }'

示例响应 (Prompt)

{
  "success": true,
  "cdpUrl": "wss://browser.firecrawl.dev/...",
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "output": "The Pro plan costs $49/month and includes unlimited scrapes, priority support, and custom integrations.",
  "stdout": "...",
  "result": "...",
  "stderr": "",
  "exitCode": 0,
  "killed": false
}

错误代码

状态	描述
`402`	浏览器会话额度不足
`403`	抓取任务属于其他团队
`404`	未找到抓取任务
`409`	回放上下文不可用——请重新运行抓取后重试
`410`	浏览器会话已被销毁
`429`	已达到浏览器会话的最大并发数
`502`	浏览器服务或 AI 代理执行失败
`503`	浏览器功能未配置 (仅限自托管)

有关详细使用方式和示例，请参见 Interact 功能指南。

授权

Authorization

string

header

必填

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

路径参数

jobId

string<uuid>

必填

抓取任务 ID

请求体

application/json

code

string

必填

要在与抓取任务绑定的浏览器沙箱中执行的代码

Required string length: 1 - 100000

language

enum<string>

默认值:node

要执行的代码语言。JavaScript 使用 node，代理浏览器 CLI 命令使用 bash。

可用选项:

python,

node,

bash

origin

string

用于执行遥测的可选来源标签

timeout

integer

默认值:30

执行超时时间（秒）

必填范围: 1 <= x <= 300

响应

代码执行成功

cdpUrl

string | null

浏览器会话的原始 Chrome DevTools Protocol (CDP) WebSocket URL。可使用它通过 Playwright、Puppeteer 或任何 CDP 客户端直接连接。

error

string | null

如果代码引发异常时的错误消息

exitCode

integer | null

执行进程的退出代码

interactiveLiveViewUrl

string | null

交互式实时视图 URL（观看者可以控制浏览器）

killed

boolean

进程是否因超时而被终止

liveViewUrl

string | null

浏览器会话的只读实时视图 URL

output

string | null

AI 代理的最终响应（仅在使用 prompt 时出现）

result

string | null

标准输出（stdout 的别名）

stderr

string | null

代码执行的标准错误输出

stdout

string | null

代码执行的标准输出

success

boolean

删除交互会话

停止交互

​路径参数

​请求体

​响应

​示例请求 (代码)

​示例响应 (代码)

​示例请求 (Prompt)

​示例响应 (Prompt)

​错误代码

授权

路径参数

请求体

响应

路径参数

请求体

响应

示例请求 (代码)

示例响应 (代码)

示例请求 (Prompt)

示例响应 (Prompt)

错误代码