Skip to main content
POST
/
scrape
/
{jobId}
/
interact
Interact with the browser session associated with a scrape job
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",
  "timeout": 30,
  "origin": "<string>"
}
'
{
  "success": true,
  "stdout": "<string>",
  "result": "<string>",
  "stderr": "<string>",
  "exitCode": 123,
  "killed": true,
  "error": "<string>"
}
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

ParameterTypeRequiredDescription
jobIdstring (UUID)YesThe scrape job ID from data.metadata.scrapeId in the scrape response

​
Request Body

ParameterTypeRequiredDefaultDescription
codestringNo—Code to execute in the browser sandbox (1–100,000 chars). Required if prompt is not set.
promptstringNo—Natural language task for the AI agent (1–10,000 chars). Required if code is not set.
languagestringNo"node"One of "python", "node", or "bash". Only used with code.
timeoutnumberNo30Execution timeout in seconds (1–300).
originstringNo—Optional origin label used for telemetry.

​
Response

FieldTypeDescription
successbooleanWhether the execution completed without errors
liveViewUrlstringRead-only live view URL for the browser session
interactiveLiveViewUrlstringInteractive live view URL (viewers can control the browser)
outputstringAI agent’s final response (only present when using prompt)
stdoutstringStandard output from the code execution
resultstringReturn value — last expression value for Node.js, final page snapshot for prompt
stderrstringStandard error output
exitCodenumberExit code of the execution (0 = success)
killedbooleanWhether the execution was terminated due to timeout
errorstringError message (only present on failure)

​
Example Request (Code)

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)

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

​
Example Request (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
  }'

​
Example Response (Prompt)

{
  "success": true,
  "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

StatusDescription
402Insufficient credits for a browser session
403Scrape job belongs to a different team
404Scrape job not found
409Replay context unavailable — rerun the scrape and try again
410Browser session has already been destroyed
429Maximum concurrent browser sessions reached
502Browser service or AI agent execution failed
503Browser feature not configured (self-hosted only)
For detailed usage with examples, see the Interact feature guide.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
jobId
string<uuid>
required

The scrape job ID

Body

application/json
​
code
string
required

Code to execute in the scrape-bound browser sandbox

Required string length: 1 - 100000
​
language
enum<string>
default:node

Language of the code to execute. Use node for JavaScript or bash for agent-browser CLI commands.

Available options:
python,
node,
bash
​
timeout
integer
default:30

Execution timeout in seconds

Required range: 1 <= x <= 300
​
origin
string

Optional origin label used for execution telemetry

Response

Code executed successfully

​
success
boolean
​
stdout
string | null

Standard output from the code execution

​
result
string | null

Standard output (alias for stdout)

​
stderr
string | null

Standard error output from the code execution

​
exitCode
integer | null

Exit code of the executed process

​
killed
boolean

Whether the process was killed due to timeout

​
error
string | null

Error message if the code raised an exception