Interact | Firecrawl

Haz scraping de una página para obtener datos limpios y luego llama a /interact para empezar a realizar acciones en esa página: hacer clic en botones, completar formularios, extraer contenido dinámico o navegar más a fondo. Solo describe lo que quieres hacer, o escribe código si necesitas un control total. Usa Interact cuando necesites:

Scraping detrás de un inicio de sesión — inicia sesión una vez y luego lee las páginas que solo aparecen tras la autenticación. Consulta Perfiles persistentes con scraping + Interact.
Avanza por la paginación con clics — pasa de página y extrae cada conjunto de resultados reutilizando una misma sesión. Consulta Interactúa mediante prompts y Ciclo de vida de la sesión.
Rellena y envía un formulario — escribe en los campos y envíalo, ya sea desde un prompt o desde código de Playwright. Consulta Interactúa mediante prompts y Ejecución de código.
Reutiliza una sesión autenticada — guarda el estado del navegador en un perfil con nombre y cárgalo en scraping posteriores. Consulta Perfiles persistentes con scraping + Interact.
Inicia una sesión sin hacer scraping primero — abre un navegador independiente que controlas directamente. Consulta Browser Sandbox.

Selecciona el modelo de interacción adecuado

Necesidad	Usar	Documentación canónica	Métodos del SDK (Node)
Iniciar una sesión del navegador independiente sin hacer scraping antes	Browser Sandbox / sesión independiente de Interact	Browser Sandbox, Crear sesión del navegador, Ejecutar código en el browser, Listar sesiones del navegador, Eliminar sesión del navegador	`browser()`, `browserExecute()`, `listBrowsers()`, `deleteBrowser()`
Continuar desde un resultado de scraping usando `scrapeId`	Interact tras el scraping	Ejecutar Interact, Detener Interact	`interact()`, `stopInteraction()`

Usa Interact vinculado al scraping cuando el flujo de trabajo comienza con POST /v2/scrape y la respuesta incluye data.metadata.scrapeId. Usa Browser Sandbox cuando necesites una sesión independiente con su propio ciclo de vida. El SDK de Python usa los equivalentes en snake_case (browser(), browser_execute(), list_browsers(), delete_browser(), interact(), stop_interaction()).

Prompts de IA

Describe qué acción quieres realizar en la página

Ejecución de código

Interactúa de forma segura mediante la ejecución de código con playwright, agent-browser

Vista en vivo

Observa o interactúa con el browser en tiempo real mediante un stream incrustable

Cómo funciona

Haz scraping de una URL con POST /v2/scrape. La respuesta incluye un scrapeId en data.metadata.scrapeId. Si quieres conservar el estado del navegador, pasa profile en esta solicitud.
Interactúa llamando a POST /v2/scrape/{scrapeId}/interact con un prompt o con código de Playwright code. No pases profile aquí; la sesión de interacción hereda el perfil del trabajo de scraping.
Detén la sesión con DELETE /v2/scrape/{scrapeId}/interact cuando hayas terminado. En los perfiles con escritura, los cambios se guardan cuando la sesión se detiene.

Inicio rápido

Haz scraping de una página, interactúa con ella y detén la sesión:

from firecrawl import Firecrawl

app = Firecrawl(
  # No se necesita API key para comenzar — añade una para límites de tasa más altos:
  # api_key="fc-YOUR-API-KEY",
)

# 1. Extraer la página principal de Amazon
result = app.scrape("https://www.amazon.com", formats=["markdown"])
scrape_id = result.metadata.scrape_id

# 2. Interactuar — buscar un producto y obtener su precio
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. Detener la sesión
app.stop_interaction(scrape_id)

import { Firecrawl } from 'firecrawl';

const app = new Firecrawl({
  // No se necesita API key para comenzar — agrega una para límites de tasa más altos:
  // apiKey: 'fc-YOUR-API-KEY',
});

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

// 2. Interactuar — buscar un producto y obtener su precio
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. Detener la sesión
await app.stopInteraction(scrapeId);

# 1. Extraer la página principal de Amazon
# No se necesita API key para comenzar — añade -H "Authorization: Bearer $FIRECRAWL_API_KEY" para límites de tasa más altos:
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. Interactuar — buscar un producto y obtener su precio
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. Detener la sesión
curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact"

# 1. Scrape la página principal de Amazon (el ID de scrape se guarda automáticamente)
firecrawl scrape https://www.amazon.com

# 2. Interactúa — busca un producto y obtén su precio
firecrawl interact "Search for iPhone 16 Pro Max"
firecrawl interact "Click on the first result and tell me the price"

# 3. Detén la sesión
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
}

Interactúa mediante prompts

La forma más simple de interactuar con una página. Describe lo que quieres en lenguaje natural y hará clic, escribirá, se desplazará y extraerá datos automáticamente.

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);

# Primero haz scraping para obtener un scrapeId
# No se necesita API key para comenzar — agrega -H "Authorization: Bearer $FIRECRAWL_API_KEY" para límites de tasa más altos:
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?"

La respuesta incluye un campo output con la respuesta del 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
}

Mantén los prompts pequeños y enfocados

Los prompts funcionan mejor cuando cada uno consiste en una única tarea clara. En lugar de pedirle al agente que realice un flujo de trabajo complejo de varios pasos de una sola vez, divídelo en llamadas interact independientes. Cada llamada reutiliza la misma sesión del navegador, por lo que el estado se conserva entre una y otra.

Ejecución de código

Para tener control total, puedes ejecutar código directamente en el sandbox del navegador. La variable page (un objeto Page de Playwright) está disponible en Node.js y Python. El modo Bash incluye agent-browser preinstalado. También puedes hacer capturas de pantalla dentro de la sesión: usa (await page.screenshot()).toString("base64") en Node.js, await page.screenshot(path="/tmp/screenshot.png") en Python o agent-browser screenshot en Bash.

Node.js (Playwright)

El lenguaje predeterminado. Escribe código de Playwright directamente. page ya está conectado al navegador.

response = app.interact(scrape_id, code="""
// Hacer clic en un botón y esperar la navegación
await page.click('#next-page');
await page.waitForLoadState('networkidle');

// Extraer contenido de la nueva 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: `
    // Hacer clic en un botón y esperar la navegación
    await page.click('#next-page');
    await page.waitForLoadState('networkidle');

    // Extraer contenido de la nueva 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);

# Haz primero un scraping para obtener un scrapeId
# No se necesita API key para comenzar — agrega -H "Authorization: Bearer $FIRECRAWL_API_KEY" para límites de tasa más 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 el último scrape automáticamente
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 });
"

# O pasa un ID de scrape explícitamente
# firecrawl interact <scrape-id> -c "await page.title()"

Python

Configura language como "python" para usar la API de Python de 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);

# Primero haz scraping para obtener un scrapeId
# No se necesita API key para comenzar — agrega -H "Authorization: Bearer $FIRECRAWL_API_KEY" para obtener límites de tasa más 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": "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 es una CLI preinstalada en el sandbox con más de 60 comandos. Proporciona un árbol de accesibilidad con referencias de elementos (@e1, @e2, …), lo que es ideal para la automatización controlada por LLM.

# Tomar una instantánea para ver los elementos interactivos
snapshot = app.interact(
    scrape_id,
    code="agent-browser snapshot -i",
    language="bash",
)
print(snapshot.stdout)
# Salida:
# [document]
#   @e1 [input type="text"] "Search..."
#   @e2 [button] "Search"
#   @e3 [link] "About"

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

// Tomar una instantánea para ver los elementos interactivos
const snapshot = await app.interact(scrapeId, {
  code: 'agent-browser snapshot -i',
  language: 'bash',
});
console.log(snapshot.stdout);
// Salida:
// [document]
//   @e1 [input type="text"] "Search..."
//   @e2 [button] "Search"
//   @e3 [link] "About"

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

# Primero haz scraping para obtener un scrapeId
# No se necesita API key para comenzar — agrega -H "Authorization: Bearer $FIRECRAWL_API_KEY" para mayores límites de tasa:
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')

# Tomar una instantánea para ver los elementos interactivos
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"}'

# Interactuar con los elementos utilizando @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"}'

# Tomar una instantánea para ver los elementos interactivos
firecrawl interact --bash -c "agent-browser snapshot -i"

# Interactuar con elementos utilizando @refs
firecrawl interact --bash -c 'agent-browser fill @e1 "firecrawl" && agent-browser click @e2'

Comandos comunes de agent-browser:

Comando	Descripción
`snapshot`	Árbol de accesibilidad completo con referencias de elementos
`snapshot -i`	Solo elementos interactivos
`click @e1`	Hacer clic en un elemento por referencia
`fill @e1 "text"`	Borrar el campo y escribir texto
`type @e1 "text"`	Escribir sin borrar
`press Enter`	Pulsar una tecla del teclado
`scroll down 500`	Desplazarse 500 píxeles hacia abajo
`get text @e1`	Obtener el contenido de texto
`get url`	Obtener la URL actual
`wait @e1`	Esperar a que aparezca el elemento
`wait --load networkidle`	Esperar a que la red quede inactiva
`find text "X" click`	Buscar un elemento por texto y hacer clic
`screenshot`	Tomar una captura de pantalla de la página actual
`eval "js code"`	Ejecutar JavaScript en la página

vista en vivo

Cada respuesta de interact devuelve una liveViewUrl que puedes incrustar para ver el navegador en tiempo real. Es útil para depuración, demos o para crear interfaces con 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" />

Vista en vivo interactiva

La respuesta también incluye un interactiveLiveViewUrl. A diferencia de la vista en vivo estándar, que es solo de visualización, la vista en vivo interactiva permite a los usuarios hacer clic, escribir e interactuar con la sesión del navegador directamente a través del stream integrado. Esto resulta útil para crear interfaces de navegador orientadas al usuario, como flujos de inicio de sesión o flujos de trabajo guiados en los que los usuarios finales necesitan controlar el navegador.

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

URL de CDP

Cada respuesta de interact también devuelve una cdpUrl: la URL de WebSocket sin procesar del Chrome DevTools Protocol (CDP) para la sesión del navegador. Úsala para conectarte directamente a la sesión activa desde Playwright, Puppeteer o cualquier cliente CDP, y controlar el navegador con tu propio 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 de la sesión

Creación

La primera llamada POST /v2/scrape/{scrapeId}/interact continúa la sesión de scraping e inicia la interacción. La sesión navega desde el mismo país que el scraping: usa el location.country del scraping o, si este no especificó ningún país, Estados Unidos. No pases location a interact; configúralo en la solicitud POST /v2/scrape.

Reutilización

Las llamadas posteriores a interact sobre el mismo scrapeId reutilizan la sesión existente. El navegador permanece abierto y conserva su estado entre llamadas, por lo que puedes encadenar varias interacciones:

# Primera llamada: haz clic en una pestaña
app.interact(scrape_id, code="await page.click('#tab-2')")

# Segunda llamada: la pestaña sigue seleccionada, extrae su contenido
result = app.interact(scrape_id, code="await page.$eval('#tab-2-content', el => el.textContent)")
print(result.result)

// Primera llamada: haz clic en una pestaña
await app.interact(scrapeId, { code: "await page.click('#tab-2')" });

// Segunda llamada: la pestaña sigue seleccionada, extrae su contenido
const result = await app.interact(scrapeId, {
  code: "await page.$eval('#tab-2-content', el => el.textContent)",
});
console.log(result.result);

# Primera llamada: haz clic en una pestaña
firecrawl interact -c "await page.click('#tab-2')"

# Segunda llamada: la pestaña sigue seleccionada, extrae su contenido
firecrawl interact -c "await page.\$eval('#tab-2-content', el => el.textContent)"

Limpieza

Detén la sesión explícitamente al terminar:

app.stop_interaction(scrape_id)

await app.stopInteraction(scrapeId);

# SCRAPE_ID es el scrapeId devuelto por tu llamada anterior a POST /v2/scrape,
# por ejemplo: SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')
# No se necesita API key para comenzar — agrega -H "Authorization: Bearer $FIRECRAWL_API_KEY" para límites de tasa más altos:
curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact"

# Detiene la última sesión de scrape
firecrawl interact stop

# O detener una sesión específica por ID
# firecrawl interact stop <scrape-id>

Las sesiones también expiran automáticamente según el TTL (predeterminado: 10 minutos) o el timeout de inactividad (predeterminado: 5 minutos).

Detén siempre las sesiones al terminar para evitar Billing innecesario. Los credits se prorratean por segundo, con un cargo mínimo de un minuto de browser. Las sesiones que usan un prompt facturan 7 credits por minuto de browser; las sesiones sin prompt facturan 2. Consulta Billing para más detalles.

Perfiles persistentes con Scraping + Interact

De forma predeterminada, cada sesión de scraping + interact se inicia con un navegador limpio. Con profile, puedes guardar y reutilizar el estado del navegador (cookies, localStorage, sesiones) entre scrapings. Esto resulta útil para mantener la sesión iniciada y conservar las preferencias. Pasa el objeto profile en la solicitud inicial POST /v2/scrape. No pases profile a POST /v2/scrape/{scrapeId}/interact; la sesión de interact reutiliza la sesión del navegador y la configuración del perfil del trabajo de scraping. Detén la sesión de interact con DELETE /v2/scrape/{scrapeId}/interact para que puedan guardarse los cambios del perfil.

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"

El ciclo de vida del perfil es:

Crea el scraping con profile.name y saveChanges: true.
Ejecuta interacciones con prompt o código usando el scrapeId devuelto.
Detén la sesión para guardar cookies, localStorage y otro estado del navegador.
Inicia un scraping posterior con el mismo profile.name. Usa saveChanges: false cuando solo quieras leer el estado existente sin volver a escribir cambios.

from firecrawl import Firecrawl

app = Firecrawl(
  # No se necesita API key para comenzar — agrega una para obtener límites de tasa más altos:
  # api_key="fc-YOUR-API-KEY",
)

# Sesión 1: Scrape con un perfil, inicia sesión y luego detén (el estado se guarda)
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)

# Sesión 2: Scrape con el mismo perfil en modo de solo lectura — ya con sesión iniciada
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({
  // No se necesita API key para comenzar — agrega una para obtener límites de tasa más altos:
  // apiKey: 'fc-YOUR-API-KEY',
});

// Sesión 1: Scrape con un perfil, inicia sesión y luego detén (el estado se guarda)
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);

// Sesión 2: Scrape con el mismo perfil en modo de solo lectura — ya con sesión iniciada
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
# No se necesita API key para comenzar — agrega -H "Authorization: Bearer $FIRECRAWL_API_KEY" para límites de tasa más 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"}'

# Detener - el estado se guarda en el perfil
curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact"

# Sesión 2: Scrape nuevamente con el mismo perfil en modo de solo lectura - ya con sesión iniciada
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"}'

# Sesión 1: Scrape con un perfil, inicia sesión y luego detén (el estado se guarda)
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

# Sesión 2: Scrape con el mismo perfil — ya has iniciado sesión
firecrawl scrape https://app.example.com/dashboard --profile my-app
firecrawl interact "Extract the dashboard data"
firecrawl interact stop

# Solo lectura: carga el estado del perfil sin guardar los cambios
firecrawl scrape https://app.example.com/dashboard --profile my-app --no-save-changes

Parámetro	Predeterminado	Descripción
`name`	None	Nombre del perfil persistente. Los scrapings con el mismo nombre comparten el estado del navegador.
`saveChanges`	`true`	Cuando es `true`, el estado del navegador se vuelve a guardar en el perfil cuando se detiene la sesión de interact. Establécelo en `false` para cargar datos existentes sin escribir cambios, lo que resulta útil cuando necesitas varios lectores concurrentes.

Solo una sesión puede guardar en un perfil a la vez. Si otra sesión ya está guardando, recibirás un error 409. Aun así, puedes abrir el mismo perfil con saveChanges: false o volver a intentarlo más tarde.

El estado del navegador se guarda cuando se detiene la sesión de interact. Detén siempre la sesión cuando termines para que el perfil pueda reutilizarse.

Validar la persistencia

Puedes probar la persistencia sin depender de un flujo de inicio de sesión real: escribe un valor en localStorage en una sesión, detenla y luego lee ese valor en una segunda sesión con el mismo perfil.

cURL

# Sesión 1: escribir el estado del navegador y guardarlo
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"

# Sesión 2: cargar el mismo perfil en modo de solo lectura y verificar el valor
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": false }
  }')

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: localStorage.getItem(\"firecrawlProfileCheck\"), cookie: document.cookie.includes(\"firecrawl_profile_check=saved\") }));"
  }'

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

La segunda respuesta de Interact debería mostrar localStorage como "saved" y cookie como true.

Puede que los perfiles creados a través de la API todavía no aparezcan en Dashboard > Interact > Profiles. Actualmente, el dashboard no ofrece un inventario completo de los perfiles persistentes creados mediante la API.

Retención cero de datos (ZDR)

Interact admite la Retención cero de datos (ZDR) para equipos con requisitos estrictos de tratamiento de datos. Cuando está habilitada, Firecrawl no conservará ningún contenido de página ni salida de ejecución una vez finalizada la sesión. Para habilitar ZDR, establece zeroDataRetention: true en tu primera llamada a interact:

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

También puedes pasar zeroDataRetention: true al crear una sesión independiente con POST /v2/interact. Al interactuar con una extracción de datos web que ya se realizó con zeroDataRetention: true, se inicia automáticamente una sesión ZDR. La política de retención se guarda en la sesión, por lo que las llamadas posteriores a esa misma sesión se mantienen en modo ZDR aunque omitan la opción. ZDR está disponible en los planes Enterprise y debe estar habilitado para tu equipo. Las solicitudes que establecen zeroDataRetention: true desde un equipo que no tiene ZDR habilitado devuelven un 403. Visita firecrawl.dev/enterprise para empezar.

Las grabaciones de sesión y los perfiles persistentes no están disponibles en modo ZDR. Las solicitudes que combinan zeroDataRetention: true con recordSession o profile devuelven un 400.
Una sesión existente que se inició sin ZDR no se puede cambiar a ZDR. Si solicitas ZDR en ella, se devuelve un 409: detén la sesión e inicia una nueva con zeroDataRetention: true.
Las extracciones de datos web con ZDR no conservan la URL extraída, por lo que es posible que Firecrawl no pueda reconstruir el navegador a partir de la extracción de datos web original. Si interact devuelve un 409 indicando que el contexto de reproducción no está disponible, pasa url en la solicitud para abrir esa página en una nueva sesión ZDR. Las acciones de la extracción de datos web original no se vuelven a ejecutar.

Consulta Precios para conocer los costos de las sesiones ZDR.

Cuándo usar cada opción

Caso de uso	Recomendado	Por qué
Búsqueda web	Search	Endpoint de búsqueda específico
Obtener contenido limpio de una URL	scraping	Una llamada a la API, sin necesidad de sesión
Hacer clic, escribir y navegar en una página	Interact (prompt)	Solo descríbelo en inglés
Extraer datos tras interacciones	Interact (prompt)	No se necesitan selectores
Lógica de scraping compleja	Interact (code)	Control total de Playwright

Interact vs Browser Sandbox: Interact se basa en la misma infraestructura que Browser Sandbox, pero ofrece una mejor interfaz para el patrón más común: hacer scraping de una página y luego profundizar. Browser Sandbox es mejor cuando necesitas una sesión del navegador independiente que no esté vinculada a un scraping específico.

Precios

Solo código (sin prompt): 2 créditos por minuto de sesión
Con prompts de IA: 7 créditos por minuto de sesión
extracción de datos web: se factura por separado (1 crédito por extracción de datos web, más cualquier costo específico del formato)
Retención cero de datos: las sesiones con ZDR suman 2 créditos por minuto de sesión, por lo que las sesiones de solo código se facturan a 4 créditos por minuto y las sesiones con prompts de IA, a 9, con el mismo mínimo de un minuto. Una extracción de datos web con ZDR mantiene además su propio costo de ZDR de 1 crédito adicional por página.

Referencia de la API

Ejecutar Interact: POST /v2/scrape/{scrapeId}/interact
Detener Interact: DELETE /v2/scrape/{scrapeId}/interact

Cuerpo de la solicitud (POST)

Campo	Tipo	Predeterminado	Descripción
`prompt`	`string`	Ninguno	Tarea en lenguaje natural para el agente de IA. Obligatorio si no se establece `code`. Máximo 10.000 caracteres.
`code`	`string`	Ninguno	Código que se va a ejecutar (Node.js, Python o Bash). Obligatorio si no se establece `prompt`. Máximo 100.000 caracteres.
`language`	`string`	`"node"`	`"node"`, `"python"` o `"bash"`. Solo se usa con `code`.
`timeout`	`number`	`30`	Timeout en segundos (1–300).
`origin`	`string`	Ninguno	Identificador del llamante para el seguimiento de la actividad.
`zeroDataRetention`	`boolean`	`false`	Ejecuta la sesión con retención cero de datos. Requiere que ZDR esté habilitado para tu equipo.
`url`	`string`	Ninguno	Página que se abrirá en una nueva sesión cuando el contexto de la extracción de datos web original no esté disponible; por ejemplo, tras una extracción de datos web con ZDR.

Respuesta

Field	Description
`success`	`true` si la ejecución se completó sin errores
`cdpUrl`	URL WebSocket sin procesar de Chrome DevTools Protocol (CDP) para la sesión del navegador. Conéctate directamente con Playwright, Puppeteer o cualquier cliente CDP
`liveViewUrl`	URL de vista en vivo de solo lectura para la sesión del navegador
`interactiveLiveViewUrl`	URL de vista en vivo interactiva (quienes la vean pueden controlar el navegador)
`output`	La respuesta en lenguaje natural del agente a tu prompt. Solo está presente cuando se utiliza `prompt`.
`stdout`	Salida estándar de la ejecución del código
`result`	Valor de retorno sin procesar del sandbox. Para `code`: la última expresión evaluada. Para `prompt`: la captura sin procesar de la página que el agente utilizó para producir `output`.
`stderr`	Salida de error estándar
`exitCode`	Código de salida (`0` = éxito)
`killed`	`true` si la ejecución se finalizó debido a timeout

¿Tienes comentarios o necesitas ayuda? Envía un correo a help@firecrawl.com o comunícate en Discord.

Primeros pasos

Endpoints principales

Más

Inicios rápidos

Guías para desarrolladores

Webhooks

Casos de uso

Otros

Contribuciones

Interact tras el scraping

Selecciona el modelo de interacción adecuado

Prompts de IA

Ejecución de código

Vista en vivo

Cómo funciona

Inicio rápido

Interactúa mediante prompts

Mantén los prompts pequeños y enfocados

Ejecución de código

Node.js (Playwright)

Python

Bash (agent-browser)

vista en vivo

Vista en vivo interactiva

URL de CDP

Ciclo de vida de la sesión

Creación

Reutilización

Limpieza

Perfiles persistentes con Scraping + Interact

Validar la persistencia

Retención cero de datos (ZDR)

Cuándo usar cada opción

Precios

Referencia de la API

Cuerpo de la solicitud (POST)

Respuesta

​Selecciona el modelo de interacción adecuado

Prompts de IA

Ejecución de código

Vista en vivo

​Cómo funciona

​Inicio rápido

​Interactúa mediante prompts

​Mantén los prompts pequeños y enfocados

​Ejecución de código

​Node.js (Playwright)

​Python

​Bash (agent-browser)

​vista en vivo

​Vista en vivo interactiva

​URL de CDP

​Ciclo de vida de la sesión

​Creación

​Reutilización

​Limpieza

​Perfiles persistentes con Scraping + Interact

​Validar la persistencia

​Retención cero de datos (ZDR)

​Cuándo usar cada opción

​Precios

​Referencia de la API

​Cuerpo de la solicitud (POST)

​Respuesta

Selecciona el modelo de interacción adecuado

Cómo funciona

Inicio rápido

Interactúa mediante prompts

Mantén los prompts pequeños y enfocados

Ejecución de código

Node.js (Playwright)

Python

Bash (agent-browser)

vista en vivo

Vista en vivo interactiva

URL de CDP

Ciclo de vida de la sesión

Creación

Reutilización

Limpieza

Perfiles persistentes con Scraping + Interact

Validar la persistencia

Retención cero de datos (ZDR)

Cuándo usar cada opción

Precios

Referencia de la API

Cuerpo de la solicitud (POST)

Respuesta