# Interact with a Scraped Page (/api-reference/endpoint/scrape-execute) Related: [Search](/api-reference/endpoint/search.md), [Search Feedback](/api-reference/endpoint/search-feedback.md), [Scrape](/api-reference/endpoint/scrape.md), [Batch Scrape](/api-reference/endpoint/batch-scrape.md), [Get Batch Scrape Status](/api-reference/endpoint/batch-scrape-get.md), [Cancel Batch Scrape](/api-reference/endpoint/batch-scrape-delete.md) Use this endpoint to continue interacting with the same browser state initialized from a previous scrape. Either `code` or `prompt` must be provided — not both. `POST /v2/scrape/{jobId}/interact` handles the full lifecycle: 1. If no browser session exists for this scrape job yet, Firecrawl creates one at the same page state as the original scrape. 2. When `code` is provided, Firecrawl runs it in the browser sandbox. When `prompt` is provided, an AI agent automates the task using natural language. 3. Later `POST /interact` calls on the same `jobId` reuse the same live browser state. When you are done, call `DELETE /v2/scrape/{jobId}/interact` to stop the session. ## Path Parameters [#path-parameters] | Parameter | Type | Required | Description | | --------- | ------------- | -------- | ---------------------------------------------------------------------- | | `jobId` | string (UUID) | Yes | The scrape job ID from `data.metadata.scrapeId` in the scrape response | ## Request Body [#request-body] | Parameter | Type | Required | Default | Description | | ---------- | ------ | -------- | -------- | ------------------------------------------------------------------------------------------ | | `code` | string | No | — | Code to execute in the browser sandbox (1–100,000 chars). Required if `prompt` is not set. | | `prompt` | string | No | — | Natural language task for the AI agent (1–10,000 chars). Required if `code` is not set. | | `language` | string | No | `"node"` | One of `"python"`, `"node"`, or `"bash"`. Only used with `code`. | | `timeout` | number | No | `30` | Execution timeout in seconds (1–300). | | `origin` | string | No | — | Optional origin label used for telemetry. | ## Response [#response] | Field | Type | Description | | ------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `success` | boolean | Whether the execution completed without errors | | `cdpUrl` | string | Raw Chrome DevTools Protocol (CDP) WebSocket URL for the browser session. Connect directly with Playwright, Puppeteer, or any CDP client | | `liveViewUrl` | string | Read-only live view URL for the browser session | | `interactiveLiveViewUrl` | string | Interactive live view URL (viewers can control the browser) | | `output` | string | AI agent's final response (only present when using `prompt`) | | `stdout` | string | Standard output from the code execution | | `result` | string | Return value — last expression value for Node.js, final page snapshot for `prompt` | | `stderr` | string | Standard error output | | `exitCode` | number | Exit code of the execution (`0` = success) | | `killed` | boolean | Whether the execution was terminated due to timeout | | `error` | string | Error message (only present on failure) | ### Example Request (Code) [#example-request-code] ```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 }' ``` ### Example Response (Code) [#example-response-code] ```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 } ``` ### Example Request (Prompt) [#example-request-prompt] ```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 }' ``` ### Example Response (Prompt) [#example-response-prompt] ```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 } ``` ### Error Codes [#error-codes] | Status | Description | | ------ | ----------------------------------------------------------- | | `402` | Insufficient credits for a browser session | | `403` | Scrape job belongs to a different team | | `404` | Scrape job not found | | `409` | Replay context unavailable — rerun the scrape and try again | | `410` | Browser session has already been destroyed | | `429` | Maximum concurrent browser sessions reached | | `502` | Browser service or AI agent execution failed | | `503` | Browser feature not configured (self-hosted only) | For detailed usage with examples, see the [Interact feature guide](/features/interact). `POST /scrape/{jobId}/interact` Interact with the browser session associated with a scrape job ## OpenAPI ```json { "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The scrape job ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "Code to execute in the scrape-bound browser sandbox" }, "language": { "type": "string", "enum": [ "python", "node", "bash" ], "default": "node", "description": "Language of the code to execute. Use `node` for JavaScript or `bash` for agent-browser CLI commands." }, "timeout": { "type": "integer", "minimum": 1, "maximum": 300, "default": 30, "description": "Execution timeout in seconds" }, "origin": { "type": "string", "description": "Optional origin label used for execution telemetry" } } } } } }, "responses": { "200": { "description": "Code executed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "cdpUrl": { "type": "string", "nullable": true, "description": "Raw Chrome DevTools Protocol (CDP) WebSocket URL for the browser session. Use it to connect directly with Playwright, Puppeteer, or any CDP client." }, "liveViewUrl": { "type": "string", "nullable": true, "description": "Read-only live view URL for the browser session" }, "interactiveLiveViewUrl": { "type": "string", "nullable": true, "description": "Interactive live view URL (viewers can control the browser)" }, "output": { "type": "string", "nullable": true, "description": "AI agent's final response (only present when using prompt)" }, "stdout": { "type": "string", "nullable": true, "description": "Standard output from the code execution" }, "result": { "type": "string", "nullable": true, "description": "Standard output (alias for stdout)" }, "stderr": { "type": "string", "nullable": true, "description": "Standard error output from the code execution" }, "exitCode": { "type": "integer", "nullable": true, "description": "Exit code of the executed process" }, "killed": { "type": "boolean", "description": "Whether the process was killed due to timeout" }, "error": { "type": "string", "nullable": true, "description": "Error message if the code raised an exception" } } } } } }, "400": { "description": "Invalid job ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Invalid job ID format." } } } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Payment required to access this resource." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Forbidden." } } } } } }, "404": { "description": "Scrape job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Job not found." } } } } } }, "409": { "description": "Scrape replay context is unavailable or session could not be initialized", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Replay context is unavailable for this scrape job. Please rerun the scrape." } } } } } }, "410": { "description": "Scrape browser session has already been destroyed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Browser session has been destroyed." } } } } } }, "429": { "description": "Too many active browser sessions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "You have reached the maximum number of active browser sessions." } } } } } }, "502": { "description": "Failed to communicate with browser service", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Failed to execute code in browser session." } } } } } } } } ```