Interactúa | Firecrawl

Extrae 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.

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

Response

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

La respuesta incluye un campo output con la respuesta del agente:

Response

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

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)

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, …) — 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",
)

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,
  "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" />

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.

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)

Limpieza

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

app.stop_interaction(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.

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(api_key="fc-YOUR-API-KEY")

# Session 1: Scrape with a profile, log in, then stop (state is saved)
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)

Parámetro	Predeterminado	Descripción
`name`	—	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.

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	Scrape	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 credits por minuto de sesión
Con prompts de IA — 7 credits por minuto de sesión
scraping — se factura por separado (1 credit por scraping, más cualquier costo específico del formato)

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`	—	Tarea en lenguaje natural para el agente de IA. Obligatorio si no se establece `code`. Máximo 10.000 caracteres.
`code`	`string`	—	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`	—	Identificador del llamante para el seguimiento de la actividad.

Respuesta

Field	Description
`success`	`true` si la ejecución se completó sin errores
`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.

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

​Ciclo de vida de la sesión

​Creación

​Reutilización

​Limpieza

​Perfiles persistentes con Scraping + Interact

​Validar la persistencia

​Cuándo usar cada opción

​Precios

​Referencia de la API

​Cuerpo de la solicitud (POST)

​Respuesta

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

Ciclo de vida de la sesión

Creación

Reutilización

Limpieza

Perfiles persistentes con Scraping + Interact

Validar la persistencia

Cuándo usar cada opción

Precios

Referencia de la API

Cuerpo de la solicitud (POST)

Respuesta