Skip to main content
Faça o scraping de uma página para obter dados limpos e, em seguida, chame /interact para começar a realizar ações nessa página - clicar em botões, preencher formulários, extrair conteúdo dinâmico ou navegar mais profundamente. Basta descrever o que você quer, ou escrever código se precisar de controle total.

Prompts de IA

Descreva a ação que você quer executar na página

Execução de código

Interaja com segurança por meio da execução de código usando playwright, agent-browser

Visualização em tempo real

Assista ou interaja com o navegador em tempo real por meio de um stream incorporável

Como funciona

  1. Faça o scraping de uma URL com POST /v2/scrape. A resposta inclui um scrapeId em data.metadata.scrapeId. Opcionalmente, passe um profile para persistir o estado do navegador entre sessões.
  2. Interaja chamando POST /v2/scrape/{scrapeId}/interact com um prompt ou com code do Playwright. Na primeira chamada, a sessão extraída é retomada e você pode começar a interagir com a página.
  3. Encerre a sessão com DELETE /v2/scrape/{scrapeId}/interact quando terminar.

Início rápido

Faça o scraping de uma página, interaja com ela e encerre a sessão:
Response

Interaja usando prompts

A forma mais simples de interagir com uma página. Descreva o que você quer em linguagem natural, e ele clicará, digitará, rolará a página e extrairá dados automaticamente.
A resposta inclui um campo output com a resposta do agente:
Response

Mantenha os Prompts Pequenos e Focados

Prompts funcionam melhor quando cada um é uma tarefa única e clara. Em vez de pedir ao agente para executar um fluxo de trabalho complexo com várias etapas de uma só vez, divida isso em chamadas interact separadas. Cada chamada reutiliza a mesma sessão do navegador, então o estado é mantido entre elas.

Executando código

Para ter controle total, você pode executar código diretamente no sandbox do navegador. A variável page (um objeto Page do Playwright) está disponível tanto em Node.js quanto em Python. O modo Bash vem com agent-browser pré-instalado. Você também pode fazer capturas de tela na sessão — use (await page.screenshot()).toString("base64") em Node.js, await page.screenshot(path="/tmp/screenshot.png") em Python ou agent-browser screenshot no Bash.

Node.js (Playwright)

A linguagem padrão. Escreva código Playwright diretamente — page já está conectado ao navegador.

Python

Defina language como "python" para a API do Python do Playwright.

Bash (agent-browser)

agent-browser é uma CLI pré-instalada no sandbox com mais de 60 comandos. Ela fornece uma árvore de acessibilidade com refs de elementos (@e1, @e2, …) — ideal para automação conduzida por LLM.
Comandos comuns do agent-browser:

Visualização em tempo real

Toda resposta de interact retorna uma liveViewUrl que você pode incorporar para acompanhar o navegador em tempo real. Útil para depuração, demonstrações ou para criar UIs com navegador.
Response

Visualização em tempo real interativa

A resposta também inclui uma interactiveLiveViewUrl. Diferentemente da visualização em tempo real padrão, que é somente para visualização, a visualização em tempo real interativa permite que os usuários cliquem, digitem e interajam com a sessão do navegador diretamente pelo stream incorporado. Isso é útil para criar interfaces de navegador voltadas para o usuário final, como fluxos de login ou fluxos de trabalho guiados em que os usuários finais precisam controlar o navegador.

Ciclo de vida da sessão

Criação

A primeira POST /v2/scrape/{scrapeId}/interact dá continuidade à sessão de scraping e inicia a interação.

Reutilização

Chamadas subsequentes de interact no mesmo scrapeId reutilizam a sessão existente. O navegador permanece aberto e mantém seu estado entre as chamadas, para que você possa encadear várias interações:

Limpeza

Encerre a sessão explicitamente quando terminar:
As sessões também expiram automaticamente com base no TTL (default: 10 minutes) ou no tempo limite de inatividade (default: 5 minutes).
Sempre encerre as sessões quando terminar para evitar cobrança desnecessária. Os créditos são rateados por segundo.

Perfis persistentes

Por padrão, cada sessão de scraping + interact começa com um navegador limpo. Com profile, você pode salvar e reutilizar o estado do navegador (cookies, localStorage, sessões) entre scrapes. Isso é útil para continuar conectado e preservar preferências. Passe o parâmetro profile ao chamar o scraping. Sessões com o mesmo nome de perfil compartilham o estado.
Apenas uma sessão pode salvar em um perfil por vez. Se outra sessão já estiver salvando, você receberá um erro 409. Você ainda pode abrir o mesmo perfil com saveChanges: false ou tentar novamente mais tarde.
O estado do navegador é salvo quando a sessão de interact é encerrada. Sempre encerre a sessão quando terminar para que o perfil possa ser reutilizado.

Quando usar o quê

Interact vs Browser Sandbox: O Interact é construído sobre a mesma infraestrutura que o Browser Sandbox, mas oferece uma interface melhor para o padrão mais comum — fazer scrape de uma página e depois se aprofundar. O Browser Sandbox é melhor quando você precisa de uma sessão do navegador independente que não esteja vinculada a um scrape específico.

Preços

  • Somente código (sem prompt) — 2 créditos por minuto de sessão
  • Com prompts de IA — 7 créditos por minuto de sessão
  • Scraping — cobrado separadamente (1 crédito por scraping, além de quaisquer custos específicos do formato)

Referência da API

Corpo da Requisição (POST)

Resposta


Tem feedback ou precisa de ajuda? Envie um e-mail para help@firecrawl.com ou entre em contato no Discord.