interagir | Firecrawl

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. Use interagir quando você precisar:

Faça scraping atrás de um login — faça login uma vez e depois leia as páginas que só aparecem após a autenticação. Veja Perfis persistentes com Scrape + interagir.
Navegue pela paginação — avance de página e colete cada conjunto de resultados, reutilizando uma única sessão. Veja interagir usando prompts e ciclo de vida da sessão.
Preencha e envie um formulário — digite nos campos e envie, a partir de um prompt ou de código Playwright. Veja interagir usando prompts e Executando código.
Reutilize uma sessão autenticada — salve o estado do navegador em um perfil nomeado e carregue-o em scrapings posteriores. Veja Perfis persistentes com Scrape + interagir.
Inicie uma sessão sem fazer scraping antes — abra um navegador independente, controlado diretamente por você. Veja Browser Sandbox.

Escolha o modelo de interação certo

Necessidade	Use	Documentação canônica	Métodos do SDK (Node)
Inicie uma sessão autônoma do navegador sem fazer scraping antes	Browser Sandbox / sessão autônoma do interagir	Browser Sandbox, Criar sessão do navegador, Executar código no navegador, Listar sessões do navegador, Excluir sessão do navegador	`browser()`, `browserExecute()`, `listBrowsers()`, `deleteBrowser()`
Continue a partir de um resultado de scraping usando `scrapeId`	Interagir após o scraping	Executar interagir, Stop interagir	`interact()`, `stopInteraction()`

Use o interagir vinculado ao scraping quando o fluxo de trabalho começar com POST /v2/scrape e a resposta incluir data.metadata.scrapeId. Use o Browser Sandbox quando precisar de uma sessão autônoma com seu próprio ciclo de vida. O SDK Python usa os equivalentes em snake_case (browser(), browser_execute(), list_browsers(), delete_browser(), interact(), stop_interaction()).

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

Faça o scraping de uma URL com POST /v2/scrape. A resposta inclui um scrapeId em data.metadata.scrapeId. Se você quiser persistir o estado do navegador, passe profile nesta solicitação.
Interaja chamando POST /v2/scrape/{scrapeId}/interact com um prompt ou com code do Playwright. Não passe profile aqui; a sessão de interação herda o perfil do job de scraping.
Encerre a sessão com DELETE /v2/scrape/{scrapeId}/interact quando terminar. Para perfis graváveis, as mudanças são salvas quando a sessão é encerrada.

Início rápido

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

from firecrawl import Firecrawl

app = Firecrawl(
  # Nenhuma API key necessária para começar — adicione uma para limites de taxa maiores:
  # api_key="fc-YOUR-API-KEY",
)

# 1. Fazer scraping da página inicial da Amazon
result = app.scrape("https://www.amazon.com", formats=["markdown"])
scrape_id = result.metadata.scrape_id

# 2. Interagir — buscar um produto e obter seu preço
app.interact(scrape_id, prompt="Search for iPhone 16 Pro Max")
response = app.interact(scrape_id, prompt="Click on the first result and tell me the price")
print(response.output)

# 3. Encerrar a sessão
app.stop_interaction(scrape_id)

import { Firecrawl } from 'firecrawl';

const app = new Firecrawl({
  // Nenhuma API key necessária para começar — adicione uma para limites de taxa mais altos:
  // apiKey: 'fc-YOUR-API-KEY',
});

// 1. Fazer scraping da página inicial da Amazon
const result = await app.scrape('https://www.amazon.com', { formats: ['markdown'] });
const scrapeId = result.metadata?.scrapeId;

// 2. Interagir — buscar um produto e obter seu preço
await app.interact(scrapeId, { prompt: 'Search for iPhone 16 Pro Max' });
const response = await app.interact(scrapeId, { prompt: 'Click on the first result and tell me the price' });
console.log(response.output);

// 3. Encerrar a sessão
await app.stopInteraction(scrapeId);

# 1. Fazer scraping da página inicial da Amazon
# Nenhuma API key necessária para começar — adicione -H "Authorization: Bearer $FIRECRAWL_API_KEY" para limites de taxa maiores:
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.amazon.com", "formats": ["markdown"]}')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

# 2. Interagir — buscar um produto e obter seu preço
curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Search for iPhone 16 Pro Max"}'

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Click on the first result and tell me the price"}'

# 3. Encerrar a sessão
curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact"

# 1. Faça scraping da página inicial da Amazon (o ID de scraping é salvo automaticamente)
firecrawl scrape https://www.amazon.com

# 2. Interaja — busque um produto e obtenha seu preço
firecrawl interact "Search for iPhone 16 Pro Max"
firecrawl interact "Click on the first result and tell me the price"

# 3. Encerre a sessão
firecrawl interact stop

Response

{
  "success": true,
  "cdpUrl": "wss://browser.firecrawl.dev/...",
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "output": "The iPhone 16 Pro Max (256GB) is priced at $1,199.00.",
  "exitCode": 0,
  "killed": false
}

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.

response = app.interact(scrape_id, prompt="What are the customer reviews saying about battery life?")
print(response.output)

const response = await app.interact(scrapeId, {
  prompt: 'What are the customer reviews saying about battery life?',
});
console.log(response.output);

# Faça o scraping primeiro para obter um scrapeId
# Nenhuma API key necessária para começar — adicione -H "Authorization: Bearer $FIRECRAWL_API_KEY" para limites de taxa maiores:
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.amazon.com", "formats": ["markdown"]}')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What are the customer reviews saying about battery life?"
  }'

firecrawl interact "What are the customer reviews saying about battery life?"

A resposta inclui um campo output com a resposta do agente:

Response

{
  "success": true,
  "cdpUrl": "wss://browser.firecrawl.dev/...",
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "output": "Customers are generally positive about battery life. Most reviewers report 8-10 hours of use on a single charge. A few noted it drains faster with heavy multitasking.",
  "stdout": "...",
  "result": "...",
  "stderr": "",
  "exitCode": 0,
  "killed": false
}

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.

response = app.interact(scrape_id, code="""
// Clique em um botão e aguarde a navegação
await page.click('#next-page');
await page.waitForLoadState('networkidle');

// Extraia o conteúdo da nova página
const title = await page.title();
const content = await page.$eval('.article-body', el => el.textContent);
JSON.stringify({ title, content });
""")
print(response.result)

const response = await app.interact(scrapeId, {
  code: `
    // Clica em um botão e aguarda a navegação
    await page.click('#next-page');
    await page.waitForLoadState('networkidle');

    // Extrai o conteúdo da nova página
    const title = await page.title();
    const content = await page.$eval('.article-body', el => el.textContent);
    JSON.stringify({ title, content });
  `,
});
console.log(response.result);

# Faça o scraping primeiro para obter um scrapeId
# Nenhuma chave de API é necessária para começar — adicione -H "Authorization: Bearer $FIRECRAWL_API_KEY" para limites de taxa mais altos:
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "formats": ["markdown"]}')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "await page.click(\"#next-page\"); await page.waitForLoadState(\"networkidle\"); const title = await page.title(); JSON.stringify({ title });",
    "language": "node",
    "timeout": 30
  }'

# Usa o último scraping automaticamente
firecrawl interact -c "
  await page.click('#next-page');
  await page.waitForLoadState('networkidle');
  const title = await page.title();
  const content = await page.\$eval('.article-body', el => el.textContent);
  JSON.stringify({ title, content });
"

# Ou passe um ID de scraping explicitamente
# firecrawl interact <scrape-id> -c "await page.title()"

Python

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

response = app.interact(
    scrape_id,
    code="""
import json

await page.click('#load-more')
await page.wait_for_load_state('networkidle')

items = await page.query_selector_all('.item')
data = []
for item in items:
    text = await item.text_content()
    data.append(text.strip())

print(json.dumps(data))
""",
    language="python",
)
print(response.stdout)

const response = await app.interact(scrapeId, {
  code: `
import json

await page.click('#load-more')
await page.wait_for_load_state('networkidle')

items = await page.query_selector_all('.item')
data = []
for item in items:
    text = await item.text_content()
    data.append(text.strip())

print(json.dumps(data))
`,
  language: 'python',
});
console.log(response.stdout);

# Faça o scraping primeiro para obter um scrapeId
# Nenhuma chave de API é necessária para começar — adicione -H "Authorization: Bearer $FIRECRAWL_API_KEY" para limites de taxa maiores:
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "formats": ["markdown"]}')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import json\nawait page.click(\"#load-more\")\nawait page.wait_for_load_state(\"networkidle\")\nitems = await page.query_selector_all(\".item\")\ndata = [await i.text_content() for i in items]\nprint(json.dumps(data))",
    "language": "python"
  }'

firecrawl interact --python -c "
import json
await page.click('#load-more')
await page.wait_for_load_state('networkidle')
items = await page.query_selector_all('.item')
data = [await i.text_content() for i in items]
print(json.dumps(data))
"

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, …), o que é ideal para automação conduzida por LLM.

# Tire um snapshot para ver elementos interativos
snapshot = app.interact(
    scrape_id,
    code="agent-browser snapshot -i",
    language="bash",
)
print(snapshot.stdout)
# Resultado:
# [document]
#   @e1 [input type="text"] "Search..."
#   @e2 [button] "Search"
#   @e3 [link] "About"

# Interaja com elementos usando @refs
app.interact(
    scrape_id,
    code='agent-browser fill @e1 "firecrawl" && agent-browser click @e2',
    language="bash",
)

// Tire um snapshot para ver elementos interativos
const snapshot = await app.interact(scrapeId, {
  code: 'agent-browser snapshot -i',
  language: 'bash',
});
console.log(snapshot.stdout);
// Resultado:
// [document]
//   @e1 [input type="text"] "Search..."
//   @e2 [button] "Search"
//   @e3 [link] "About"

// Interaja com elementos usando @refs
await app.interact(scrapeId, {
  code: 'agent-browser fill @e1 "firecrawl" && agent-browser click @e2',
  language: 'bash',
});

# Faça o scraping primeiro para obter um scrapeId
# Nenhuma API key necessária para começar — adicione -H "Authorization: Bearer $FIRECRAWL_API_KEY" para limites de taxa maiores:
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "formats": ["markdown"]}')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

# Tire um snapshot para ver elementos interativos
curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"code": "agent-browser snapshot -i", "language": "bash"}'

# Interaja com elementos usando @refs
curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"code": "agent-browser fill @e1 \"firecrawl\" && agent-browser click @e2", "language": "bash"}'

# Tire um snapshot para ver elementos interativos
firecrawl interact --bash -c "agent-browser snapshot -i"

# Interaja com elementos usando @refs
firecrawl interact --bash -c 'agent-browser fill @e1 "firecrawl" && agent-browser click @e2'

Comandos comuns do agent-browser:

Comando	Descrição
`snapshot`	Árvore de acessibilidade completa com refs de elementos
`snapshot -i`	Apenas elementos interativos
`click @e1`	Clica no elemento pela ref
`fill @e1 "text"`	Limpa o campo e digita o texto
`type @e1 "text"`	Digita sem limpar
`press Enter`	Pressiona uma tecla do teclado
`scroll down 500`	Rola 500 pixels para baixo
`get text @e1`	Obtém o conteúdo de texto
`get url`	Obtém a URL atual
`wait @e1`	Aguarda o elemento
`wait --load networkidle`	Aguarda a rede ficar inativa
`find text "X" click`	Encontra o elemento pelo texto e clica
`screenshot`	Tira uma captura de tela da página atual
`eval "js code"`	Executa JavaScript na página

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

{
  "success": true,
  "cdpUrl": "wss://browser.firecrawl.dev/...",
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "stdout": "",
  "result": "...",
  "exitCode": 0
}

<iframe src="LIVE_VIEW_URL" width="100%" height="600" />

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.

<iframe src="INTERACTIVE_LIVE_VIEW_URL" width="100%" height="600" />

URL do CDP

Toda resposta de interação também retorna uma cdpUrl: a URL WebSocket bruta do Chrome DevTools Protocol (CDP) da sessão do navegador. Use-a para se conectar diretamente à sessão ativa pelo Playwright, Puppeteer ou qualquer cliente CDP e controlar o navegador com seu próprio código.

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP(cdpUrl);
const context = browser.contexts()[0];
const page = context.pages()[0];

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. A sessão navega a partir do mesmo país do scraping: ela usa o location.country do scraping ou, se nenhum país tiver sido definido no scraping, os EUA. Não passe location para o interagir; defina-o na request POST /v2/scrape.

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:

# Primeira chamada: clicar em uma aba
app.interact(scrape_id, code="await page.click('#tab-2')")

# Segunda chamada: a aba ainda está selecionada, extrair seu conteúdo
result = app.interact(scrape_id, code="await page.$eval('#tab-2-content', el => el.textContent)")
print(result.result)

// Primeira chamada: clicar em uma aba
await app.interact(scrapeId, { code: "await page.click('#tab-2')" });

// Segunda chamada: a aba ainda está selecionada, extrair seu conteúdo
const result = await app.interact(scrapeId, {
  code: "await page.$eval('#tab-2-content', el => el.textContent)",
});
console.log(result.result);

# Primeira chamada: clicar em uma aba
firecrawl interact -c "await page.click('#tab-2')"

# Segunda chamada: a aba ainda está selecionada, extrair seu conteúdo
firecrawl interact -c "await page.\$eval('#tab-2-content', el => el.textContent)"

Limpeza

Encerre a sessão explicitamente quando terminar:

app.stop_interaction(scrape_id)

await app.stopInteraction(scrapeId);

# SCRAPE_ID é o scrapeId retornado pela sua chamada anterior a POST /v2/scrape,
# por exemplo: SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')
# Nenhuma API key necessária para começar — adicione -H "Authorization: Bearer $FIRECRAWL_API_KEY" para limites de taxa maiores:
curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact"

# Para a última sessão de scraping
firecrawl interact stop

# Ou pare uma sessão específica pelo ID
# firecrawl interact stop <scrape-id>

As sessões também expiram automaticamente com base no TTL (padrão: 10 minutes) ou no tempo limite de inatividade (padrão: 5 minutes).

Sempre encerre as sessões quando terminar para evitar cobrança desnecessária. Os créditos são rateados por segundo, com uma cobrança mínima de um minuto de navegador. Sessões que usam um prompt consomem 7 créditos por minuto de navegador; sessões sem um prompt consomem 2. Consulte cobrança para ver os detalhes.

Perfis persistentes com Scrape + Interagir

Por padrão, cada sessão de scraping + interagir 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 objeto profile na requisição inicial POST /v2/scrape. Não passe profile para POST /v2/scrape/{scrapeId}/interact; a sessão de interagir reutiliza a sessão do navegador e as configurações de perfil do scrape job. Encerre a sessão de interagir com DELETE /v2/scrape/{scrapeId}/interact para que mudanças graváveis no perfil possam ser salvas.

cURL

curl -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown"],
    "profile": {
      "name": "my-profile",
      "saveChanges": true
    }
  }'

curl -X POST "https://api.firecrawl.dev/v2/scrape/SCRAPE_ID/interact" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Click the login button"
  }'

curl -X DELETE "https://api.firecrawl.dev/v2/scrape/SCRAPE_ID/interact" \
  -H "Authorization: Bearer fc-YOUR_API_KEY"

O ciclo de vida do perfil é:

Crie o scraping com profile.name e saveChanges: true.
Execute interações por prompt ou código usando o scrapeId retornado.
Encerre a sessão para salvar cookies, localStorage e outros estados do navegador.
Inicie um scraping posterior com o mesmo profile.name. Use saveChanges: false quando quiser apenas ler o estado existente sem gravar as mudanças de volta.

from firecrawl import Firecrawl

app = Firecrawl(
  # Nenhuma API key necessária para começar — adicione uma para limites de taxa mais altos:
  # api_key="fc-YOUR-API-KEY",
)

# Sessão 1: Scraping com um perfil, autentique-se e encerre (o estado é salvo)
result = app.scrape(
    "https://app.example.com/login",
    formats=["markdown"],
    profile={"name": "my-app", "save_changes": True},
)
scrape_id = result.metadata.scrape_id

app.interact(scrape_id, prompt="Fill in user@example.com and password, then click Login")
app.stop_interaction(scrape_id)

# Sessão 2: Scraping com o mesmo perfil em modo somente leitura - já autenticado
result = app.scrape(
    "https://app.example.com/dashboard",
    formats=["markdown"],
    profile={"name": "my-app", "save_changes": False},
)
scrape_id = result.metadata.scrape_id

response = app.interact(scrape_id, prompt="Extract the dashboard data")
print(response.output)
app.stop_interaction(scrape_id)

import { Firecrawl } from 'firecrawl';

const app = new Firecrawl({
  // Nenhuma API key necessária para começar — adicione uma para limites de taxa mais altos:
  // apiKey: 'fc-YOUR-API-KEY',
});

// Session 1: Scrape com um perfil, faça login e pare (o estado é salvo)
const result1 = await app.scrape('https://app.example.com/login', {
  formats: ['markdown'],
  profile: { name: 'my-app', saveChanges: true },
});
const scrapeId1 = result1.metadata?.scrapeId;

await app.interact(scrapeId1, { prompt: 'Fill in user@example.com and password, then click Login' });
await app.stopInteraction(scrapeId1);

// Sessão 2: Scraping com o mesmo perfil em modo somente leitura - já autenticado
const result2 = await app.scrape('https://app.example.com/dashboard', {
  formats: ['markdown'],
  profile: { name: 'my-app', saveChanges: false },
});
const scrapeId2 = result2.metadata?.scrapeId;

const response = await app.interact(scrapeId2, { prompt: 'Extract the dashboard data' });
console.log(response.output);
await app.stopInteraction(scrapeId2);

# Session 1: Scrape with a profile
# Nenhuma API key necessária para começar — adicione -H "Authorization: Bearer $FIRECRAWL_API_KEY" para limites de taxa mais altos:
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/login",
    "formats": ["markdown"],
    "profile": { "name": "my-app", "saveChanges": true }
  }')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

# Log in via interact
curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Fill in user@example.com and password, then click Login"}'

# Parar — o estado é salvo no perfil
curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact"

# Sessão 2: Scraping novamente com o mesmo perfil em modo somente leitura — já autenticado
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/dashboard",
    "formats": ["markdown"],
    "profile": { "name": "my-app", "saveChanges": false }
  }')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Extract the dashboard data"}'

# Sessão 1: Scraping com um perfil, faça login e pare (estado é salvo)
firecrawl scrape https://app.example.com/login --profile my-app
firecrawl interact "Fill in user@example.com and password, then click Login"
firecrawl interact stop

# Sessão 2: Scraping com o mesmo perfil — já autenticado
firecrawl scrape https://app.example.com/dashboard --profile my-app
firecrawl interact "Extract the dashboard data"
firecrawl interact stop

# Somente leitura: carrega o estado do perfil sem salvar mudanças
firecrawl scrape https://app.example.com/dashboard --profile my-app --no-save-changes

Parâmetro	Padrão	Descrição
`name`	None	Um nome para o perfil persistente. Scrapes com o mesmo nome compartilham o estado do navegador.
`saveChanges`	`true`	Quando `true`, o estado do navegador é salvo novamente no perfil quando a sessão de interagir é encerrada. Defina como `false` para carregar dados existentes sem gravar, o que é útil quando você precisa de vários leitores simultâneos.

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 interagir é encerrada. Sempre encerre a sessão quando terminar para que o perfil possa ser reutilizado.

Validar a persistência

Você pode testar a persistência sem depender de um fluxo de login real gravando um valor no localStorage em uma sessão, encerrando-a e, em seguida, lendo esse valor em uma segunda sessão com o mesmo perfil.

cURL

# Sessão 1: gravar o estado do navegador e salvá-lo
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown"],
    "profile": { "name": "profile-validation", "saveChanges": true }
  }')

SCRAPE_ID=$(echo "$RESPONSE" | jq -r ".data.metadata.scrapeId")

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "await page.evaluate(() => { localStorage.setItem(\"firecrawlProfileCheck\", \"saved\"); document.cookie = \"firecrawl_profile_check=saved; path=/; max-age=3600\"; return localStorage.getItem(\"firecrawlProfileCheck\"); });"
  }'

curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

A segunda resposta do Interagir deve mostrar localStorage como "saved" e cookie como true.

Os perfis criados via API talvez ainda não apareçam em painel > Interagir > Perfis. No momento, o painel ainda não oferece uma visão completa dos perfis persistentes criados via API.

Retenção Zero de Dados (ZDR)

O interagir oferece suporte à Retenção Zero de Dados (ZDR) para equipes com requisitos rigorosos de tratamento de dados. Quando ativada, o Firecrawl não persiste nenhum conteúdo de página nem saída de execução além da duração da sessão. Para ativar a ZDR, defina zeroDataRetention: true na sua primeira chamada de interagir:

cURL

curl -X POST https://api.firecrawl.dev/v2/scrape/YOUR_SCRAPE_ID/interact \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "prompt": "Click the pricing tab and summarize the plans",
    "zeroDataRetention": true
  }'

Você também pode passar zeroDataRetention: true ao criar uma sessão independente com POST /v2/interact. Interagir com um scraping que já foi feito com zeroDataRetention: true inicia automaticamente uma sessão ZDR. A política de retenção fica armazenada na sessão, então as chamadas seguintes à mesma sessão continuam no modo ZDR, mesmo que omitam a opção. O ZDR está disponível nos planos Enterprise e precisa ser habilitado para a sua equipe. Requisições que definem zeroDataRetention: true a partir de uma equipe sem ZDR habilitado retornam um 403. Acesse firecrawl.dev/enterprise para começar.

Gravações de sessão e perfis persistentes não estão disponíveis no modo ZDR. Requisições que combinam zeroDataRetention: true com recordSession ou profile retornam um 400.
Uma sessão existente iniciada sem ZDR não pode ser convertida para ZDR. Solicitar ZDR nela retorna um 409: pare a sessão e inicie uma nova com zeroDataRetention: true.
Raspagens com ZDR não retêm a URL extraída, então o Firecrawl pode não conseguir reconstruir o navegador a partir do scraping original. Se o interagir retornar um 409 informando que o contexto de replay não está disponível, passe url na request para abrir essa página em uma nova sessão ZDR. As ações do scraping original não são reexecutadas.

Veja Preços para conferir os custos das sessões ZDR.

Quando usar o quê

Use Case	Recommended	Why
Busca na web	Search	Endpoint de busca dedicado
Obter conteúdo limpo de uma URL	Scrape	Uma chamada de API, sem necessidade de sessão
Clicar, digitar e navegar em uma página	Interagir (prompt)	Basta descrever em inglês
Extrair dados por trás das interações	Interagir (prompt)	Não são necessários seletores
Lógica de scraping complexa	Interagir (code)	Controle total do Playwright

Interagir vs Browser Sandbox: O Interagir é 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)
Retenção Zero de Dados: sessões com ZDR acrescentam 2 créditos por minuto de sessão. Assim, sessões somente com código são cobradas a 4 créditos por minuto e sessões com prompts de IA, a 9, com o mesmo mínimo de um minuto. Um scraping com ZDR continua tendo seu próprio custo de ZDR, de 1 crédito adicional por página.

Referência da API

Execute Interagir: POST /v2/scrape/{scrapeId}/interact
Stop Interagir: DELETE /v2/scrape/{scrapeId}/interact

Corpo da Requisição (POST)

Campo	Tipo	Padrão	Descrição
`prompt`	`string`	Nenhum	Tarefa em linguagem natural para o agente de IA. Obrigatório se `code` não estiver definido. Máx. 10.000 caracteres.
`code`	`string`	Nenhum	Código a ser executado (Node.js, Python ou Bash). Obrigatório se `prompt` não estiver definido. Máx. 100.000 caracteres.
`language`	`string`	`"node"`	`"node"`, `"python"` ou `"bash"`. Usado apenas com `code`.
`timeout`	`number`	`30`	Tempo limite em segundos (1–300).
`origin`	`string`	Nenhum	Identificador do chamador para acompanhamento de atividades.
`zeroDataRetention`	`boolean`	`false`	Executa a sessão com Retenção Zero de Dados. Requer que o ZDR esteja habilitado para sua equipe.
`url`	`string`	Nenhum	Página a ser aberta em uma nova sessão quando o contexto do scraping original não estiver disponível, como após um scraping com ZDR.

Resposta

Field	Description
`success`	`true` se a execução for concluída sem erros
`cdpUrl`	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`	URL de visualização em tempo real somente leitura para a sessão do navegador
`interactiveLiveViewUrl`	URL de visualização em tempo real interativa (os visualizadores podem controlar o navegador)
`output`	A resposta em linguagem natural do agente ao seu prompt. Presente apenas ao usar `prompt`.
`stdout`	Saída padrão da execução do código
`result`	Valor bruto retornado do sandbox. Para `code`: a última expressão avaliada. Para `prompt`: o snapshot bruto da página que o agente usou para produzir `output`.
`stderr`	Saída de erro padrão
`exitCode`	Código de saída (`0` = sucesso)
`killed`	`true` se a execução tiver sido encerrada devido a tempo limite

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

Primeiros passos

Endpoints principais

Mais

Guias de início rápido

Guias para desenvolvedores

Webhooks

Casos de uso

Outros

Como contribuir

Interaja após o scraping

Escolha o modelo de interação certo

Prompts de IA

Execução de código

Visualização em tempo real

Como funciona

Início rápido

Interaja usando prompts

Mantenha os Prompts Pequenos e Focados

Executando código

Node.js (Playwright)

Python

Bash (agent-browser)

Visualização em tempo real

Visualização em tempo real interativa

URL do CDP

Ciclo de vida da sessão

Criação

Reutilização

Limpeza

Perfis persistentes com Scrape + Interagir

Validar a persistência

Retenção Zero de Dados (ZDR)

Quando usar o quê

Preços

Referência da API

Corpo da Requisição (POST)

Resposta

​Escolha o modelo de interação certo

Prompts de IA

Execução de código

Visualização em tempo real

​Como funciona

​Início rápido

​Interaja usando prompts

​Mantenha os Prompts Pequenos e Focados

​Executando código

​Node.js (Playwright)

​Python

​Bash (agent-browser)

​Visualização em tempo real

​Visualização em tempo real interativa

​URL do CDP

​Ciclo de vida da sessão

​Criação

​Reutilização

​Limpeza

​Perfis persistentes com Scrape + Interagir

​Validar a persistência

​Retenção Zero de Dados (ZDR)

​Quando usar o quê

​Preços

​Referência da API

​Corpo da Requisição (POST)

​Resposta

Escolha o modelo de interação certo

Como funciona

Início rápido

Interaja usando prompts

Mantenha os Prompts Pequenos e Focados

Executando código

Node.js (Playwright)

Python

Bash (agent-browser)

Visualização em tempo real

Visualização em tempo real interativa

URL do CDP

Ciclo de vida da sessão

Criação

Reutilização

Limpeza

Perfis persistentes com Scrape + Interagir

Validar a persistência

Retenção Zero de Dados (ZDR)

Quando usar o quê

Preços

Referência da API

Corpo da Requisição (POST)

Resposta