Interagir com uma página extraída

Execute código ou um prompt de IA na sessão do navegador vinculada a um job de scraping.

POST /scrape/{jobId}/interact

Interaja com a sessão do navegador associada a um job de scraping

cURL

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

200

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

Use este endpoint para continuar interagindo com o mesmo estado do navegador iniciado a partir de um scraping anterior. É necessário fornecer code ou prompt — não ambos.

POST /v2/scrape/{jobId}/interact gerencia todo o ciclo de vida:

1. Se ainda não existir uma sessão do navegador para este job de scraping, o Firecrawl cria uma no mesmo estado da página do scraping original.
2. Quando code é fornecido, o Firecrawl o executa no sandbox do navegador. Quando prompt é fornecido, um agente de IA automatiza a tarefa usando linguagem natural.
3. Chamadas posteriores para POST /interact no mesmo jobId reutilizam o mesmo estado ativo do navegador.

Quando terminar, chame DELETE /v2/scrape/{jobId}/interact para encerrar a sessão.

​

Parâmetros do caminho

Parâmetro	Tipo	Obrigatório	Descrição
jobId	string (UUID)	Sim	O ID do job de scraping em data.metadata.scrapeId na resposta de scraping

​

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
code	string	Não	—	Código a ser executado no sandbox do navegador (1–100.000 caracteres). Obrigatório se prompt não estiver definido.
prompt	string	Não	—	Tarefa em linguagem natural para o agente de IA (1–10.000 caracteres). Obrigatório se code não estiver definido.
language	string	Não	"node"	Um de "python", "node" ou "bash". Usado apenas com code.
timeout	number	Não	30	Tempo limite de execução em segundos (1–300).
origin	string	Não	—	Rótulo de origem opcional usado para telemetria.

​

resposta

Campo	Tipo	Descrição
success	boolean	Indica se a execução foi concluída sem erros
cdpUrl	string	URL WebSocket bruta do Chrome DevTools Protocol (CDP) para a sessão do navegador. Conecte-se diretamente com Playwright, Puppeteer ou qualquer cliente CDP
liveViewUrl	string	URL de visualização em tempo real somente leitura da sessão do navegador
interactiveLiveViewUrl	string	URL de visualização em tempo real interativa (os usuários podem controlar o navegador)
output	string	Resposta final do agente de IA (presente apenas ao usar prompt)
stdout	string	Saída padrão da execução do código
result	string	Valor de retorno — valor da última expressão no Node.js, instantâneo final da página para prompt
stderr	string	Saída de erro padrão
exitCode	number	Código de saída da execução (0 = sucesso)
killed	boolean	Indica se a execução foi encerrada devido ao tempo limite
error	string	Mensagem de erro (presente apenas em caso de falha)

​

Exemplo de requisição (Código)

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

​

Exemplo de resposta (Código)

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

​

Exemplo de requisição (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
  }'

​

Exemplo de resposta (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
}

​

Códigos de erro

Status	Descrição
402	Créditos insuficientes para uma sessão do navegador
403	O job de scraping pertence a outra equipe
404	Job de scraping não encontrado
409	Contexto de replay indisponível — refaça o scraping e tente novamente
410	A sessão do navegador já foi encerrada
429	Número máximo de sessões simultâneas do navegador atingido
502	Falha no serviço de navegador ou na execução do agente de IA
503	Recurso de navegador não configurado (apenas self-hosted)

Para detalhes de uso e exemplos, consulte o guia do recurso Interact.

Autorizações

Authorization · string · header · obrigatório

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

Parâmetros de caminho

jobId · string<uuid> · obrigatório

O ID do job de scraping

Corpo

application/json

code · string · obrigatório

Código a ser executado no sandbox do navegador vinculado ao job de scraping

Required string length: 1 - 100000

language · enum<string> · padrão: node

Linguagem do código a ser executado. Use node para JavaScript ou bash para comandos CLI do agent-browser.

Opções disponíveis: python, node, bash

origin · string

Rótulo de origem opcional usado para telemetria de execução

timeout · integer · padrão: 30

Tempo limite de execução em segundos

Intervalo obrigatório: 1 <= x <= 300

Resposta

200

application/json

Código executado com sucesso

cdpUrl · string | null

URL bruta de WebSocket do Chrome DevTools Protocol (CDP) da sessão do navegador. Use-a para se conectar diretamente com Playwright, Puppeteer ou qualquer cliente CDP.

error · string | null

Mensagem de erro caso o código gere uma exceção

exitCode · integer | null

Código de saída do processo executado

interactiveLiveViewUrl · string | null

URL da visualização em tempo real interativa (os usuários podem controlar o navegador)

killed · boolean

Se o processo foi encerrado devido ao tempo limite

liveViewUrl · string | null

URL da visualização em tempo real somente leitura da sessão do navegador

output · string | null

Resposta final do agente de IA (presente apenas ao usar um prompt)

result · string | null

Saída padrão (alias de stdout)

stderr · string | null

Saída de erro padrão da execução do código

stdout · string | null

Saída padrão da execução do código

success · boolean