# 与已抓取的页面交互 (/zh/api-reference/endpoint/scrape-execute)

<!-- agent-signals: reading_time_min: 5 · est_tokens: 3130 · updated: 2026-07-30 -->
Related: [Search（搜索）](/zh/api-reference/endpoint/search.md), [搜索反馈](/zh/api-reference/endpoint/search-feedback.md), [Scrape](/zh/api-reference/endpoint/scrape.md), [批量抓取](/zh/api-reference/endpoint/batch-scrape.md), [获取批量抓取状态](/zh/api-reference/endpoint/batch-scrape-get.md), [取消批量抓取](/zh/api-reference/endpoint/batch-scrape-delete.md)

使用此端点可继续与由先前抓取初始化的同一浏览器状态进行交互。必须提供 `code` 或 `prompt` 之一，不能同时提供两者。

`POST /v2/scrape/{jobId}/interact` 负责整个生命周期：

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

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

<div id="path-parameters">
  ## 路径参数 [#路径参数]
</div>

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

<div id="request-body">
  ## 请求体 [#请求体]
</div>

| 参数         | 类型     | 必填 | 默认值      | 描述                                                  |
| ---------- | ------ | -- | -------- | --------------------------------------------------- |
| `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 | 否  | —        | 用于遥测的可选来源标识。                                        |

<div id="response">
  ## 响应 [#响应]
</div>

| 字段                       | 类型      | 描述                                                                                             |
| ------------------------ | ------- | ---------------------------------------------------------------------------------------------- |
| `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  | 错误信息 (仅在失败时返回)                                                                                 |

<div id="example-request-code">
  ### 示例请求 (代码) [#示例请求-代码]
</div>

```bash
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
  }'
```

<div id="example-response-code">
  ### 示例响应 (代码) [#示例响应-代码]
</div>

```json
{
  "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
}
```

<div id="example-request-prompt">
  ### 示例请求 (Prompt) [#示例请求-prompt]
</div>

```bash
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
  }'
```

<div id="example-response-prompt">
  ### 示例响应 (Prompt) [#示例响应-prompt]
</div>

```json
{
  "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
}
```

<div id="error-codes">
  ### 错误代码 [#错误代码]
</div>

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

有关详细使用方式和示例，请参见 [Interact 功能指南](/zh/features/interact)。

`POST /scrape/{jobId}/interact`

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

## OpenAPI

```json
{
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "description": "抓取任务 ID",
      "in": "path",
      "name": "jobId",
      "required": true,
      "schema": {
        "format": "uuid",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "properties": {
            "code": {
              "description": "要在与抓取任务绑定的浏览器沙箱中执行的代码",
              "maxLength": 100000,
              "minLength": 1,
              "type": "string"
            },
            "language": {
              "default": "node",
              "description": "要执行的代码语言。JavaScript 使用 `node`，代理浏览器 CLI 命令使用 `bash`。",
              "enum": [
                "python",
                "node",
                "bash"
              ],
              "type": "string"
            },
            "origin": {
              "description": "用于执行遥测的可选来源标签",
              "type": "string"
            },
            "timeout": {
              "default": 30,
              "description": "执行超时时间（秒）",
              "maximum": 300,
              "minimum": 1,
              "type": "integer"
            }
          },
          "required": [
            "code"
          ],
          "type": "object"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "cdpUrl": {
                "description": "浏览器会话的原始 Chrome DevTools Protocol (CDP) WebSocket URL。可使用它通过 Playwright、Puppeteer 或任何 CDP 客户端直接连接。",
                "nullable": true,
                "type": "string"
              },
              "error": {
                "description": "如果代码引发异常时的错误消息",
                "nullable": true,
                "type": "string"
              },
              "exitCode": {
                "description": "执行进程的退出代码",
                "nullable": true,
                "type": "integer"
              },
              "interactiveLiveViewUrl": {
                "description": "交互式实时视图 URL（观看者可以控制浏览器）",
                "nullable": true,
                "type": "string"
              },
              "killed": {
                "description": "进程是否因超时而被终止",
                "type": "boolean"
              },
              "liveViewUrl": {
                "description": "浏览器会话的只读实时视图 URL",
                "nullable": true,
                "type": "string"
              },
              "output": {
                "description": "AI 代理的最终响应（仅在使用 prompt 时出现）",
                "nullable": true,
                "type": "string"
              },
              "result": {
                "description": "标准输出（stdout 的别名）",
                "nullable": true,
                "type": "string"
              },
              "stderr": {
                "description": "代码执行的标准错误输出",
                "nullable": true,
                "type": "string"
              },
              "stdout": {
                "description": "代码执行的标准输出",
                "nullable": true,
                "type": "string"
              },
              "success": {
                "type": "boolean"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "代码执行成功"
    },
    "400": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "error": {
                "example": "Invalid job ID format.",
                "type": "string"
              },
              "success": {
                "example": false,
                "type": "boolean"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "无效的任务 ID"
    },
    "402": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "error": {
                "example": "Payment required to access this resource.",
                "type": "string"
              },
              "success": {
                "example": false,
                "type": "boolean"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "需要付费"
    },
    "403": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "error": {
                "example": "Forbidden.",
                "type": "string"
              },
              "success": {
                "example": false,
                "type": "boolean"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "禁止访问"
    },
    "404": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "error": {
                "example": "Job not found.",
                "type": "string"
              },
              "success": {
                "example": false,
                "type": "boolean"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "未找到抓取任务"
    },
    "409": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "error": {
                "example": "Replay context is unavailable for this scrape job. Please rerun the scrape.",
                "type": "string"
              },
              "success": {
                "example": false,
                "type": "boolean"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "抓取回放上下文不可用，或无法初始化会话"
    },
    "410": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "error": {
                "example": "Browser session has been destroyed.",
                "type": "string"
              },
              "success": {
                "example": false,
                "type": "boolean"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "抓取浏览器会话已被销毁"
    },
    "429": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "error": {
                "example": "You have reached the maximum number of active browser sessions.",
                "type": "string"
              },
              "success": {
                "example": false,
                "type": "boolean"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "活动中的浏览器会话过多"
    },
    "502": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "error": {
                "example": "Failed to execute code in browser session.",
                "type": "string"
              },
              "success": {
                "example": false,
                "type": "boolean"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "与浏览器服务通信失败"
    }
  }
}
```