Python - Firecrawl Docs

Instalación#

Para instalar el SDK de Python de Firecrawl, puedes usar pip:

Python

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

Uso#

Obtén una clave de API en firecrawl.dev y luego defínela como una variable de entorno llamada FIRECRAWL_API_KEY o pásala directamente a la clase Firecrawl.

Note

¿No tienes una clave de API? Puedes instanciar Firecrawl sin una clave y usar scrape, search e interact en el plan Free sin clave (con límite de tasa por IP — consulta Rate Limits). Todos los demás métodos requieren una clave.

Python

from firecrawl import Firecrawlfirecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")# Extraer datos de un sitio web:scrape_status = firecrawl.scrape(  'https://firecrawl.dev',   formats=['markdown', 'html'])print(scrape_status)# Rastrear un sitio web:crawl_status = firecrawl.crawl(  'https://firecrawl.dev',   limit=100,   scrape_options={    'formats': ['markdown', 'html']  })print(crawl_status)

Extracción de una URL#

Para extraer una sola URL, usa el método scrape. Devuelve el contenido de la página como datos estructurados, incluidos markdown, metadatos y cualquier otro formato que solicites.

Python

# Extraer un sitio web:scrape_result = firecrawl.scrape('firecrawl.dev', formats=['markdown', 'html'])print(scrape_result)

Note

El SDK de Python convierte todos los nombres de los campos de la respuesta de camelCase a snake_case. Por ejemplo, los campos de metadatos como ogImage, ogTitle y sourceURL de la API se convierten en og_image, og_title y source_url en la respuesta del SDK.

Análisis de archivos cargados#

Usa parse para cargar archivos locales (html, pdf, docx, xlsx, etc.) directamente en /v2/parse. parse no admite changeTracking ni opciones exclusivas del navegador, como acciones, wait_for, location, mobile, screenshot y branding.

Python

from firecrawl.v2.types import ParseOptionsparsed = firecrawl.parse(    b"<!DOCTYPE html><html><body><h1>Python Parse</h1></body></html>",    filename="upload.html",    content_type="text/html",    options=ParseOptions(formats=["markdown"]),)print(parsed.markdown)

Rastrear un sitio web#

Para rastrear un sitio web, usa el método crawl. Recibe la URL inicial y opciones opcionales como argumentos. Estas opciones te permiten definir ajustes adicionales para el trabajo de rastreo, como el número máximo de páginas a rastrear, los dominios permitidos y el formato de salida. Consulta Paginación para la paginación automática/manual y los límites.

Python

job = firecrawl.crawl(url="https://docs.firecrawl.dev", limit=5, poll_interval=1, timeout=120)print(job)

Rastreo solo del sitemap#

Usa sitemap="only" para rastrear únicamente las URLs del sitemap (la URL inicial siempre se incluye y se omite la detección de enlaces HTML).

Python

job = firecrawl.crawl(url="https://docs.firecrawl.dev", sitemap="only", limit=25)print(job.status, len(job.data))

Iniciar un rastreo#

Tip

¿Prefieres no bloquear? Consulta la sección Clase asíncrona a continuación.

Inicia un trabajo sin esperar con start_crawl. Devuelve un ID de trabajo que puedes usar para consultar el estado. Usa crawl cuando quieras un “waiter” que bloquee hasta completarse. Consulta Paginación para el comportamiento y los límites de paginado.

Python

job = firecrawl.start_crawl(url="https://docs.firecrawl.dev", limit=10)print(job)

Consultar el estado del rastreo#

Consulta el estado de un trabajo de rastreo con get_crawl_status. Pasa el ID de trabajo y obtén el estado actual junto con los resultados recopilados hasta el momento.

Python

estado = firecrawl.get_crawl_status("<crawl-id>")print(estado)

Cancelar un rastreo#

Cancela un trabajo de rastreo con el método cancel_crawl. Pasa el ID de trabajo devuelto por start_crawl para obtener el estado de la cancelación.

Python

ok = firecrawl.cancel_crawl("<crawl-id>")print("Cancelado:", ok)

Mapear un sitio web#

Usa map para generar una lista de URL de un sitio web. Las opciones te permiten personalizar el proceso de mapeo, como excluir subdominios o aprovechar el sitemap.

Python

res = firecrawl.map(url="https://firecrawl.dev", limit=10)print(res)

Ejecutar un agente#

Asigna una tarea de investigación o extracción a un agente con el método agent. Acepta un prompt, un schema opcional para estructurar la salida y max_credits para limitar el gasto de la ejecución.

Python

from firecrawl import Firecrawlfrom pydantic import BaseModel, Fieldfrom typing import List, Optionalapp = Firecrawl(api_key="fc-YOUR_API_KEY")class Founder(BaseModel):    name: str = Field(description="Full name of the founder")    role: Optional[str] = Field(None, description="Role or position")    background: Optional[str] = Field(None, description="Professional background")class FoundersSchema(BaseModel):    founders: List[Founder] = Field(description="Lista de fundadores")result = app.agent(    prompt="Find the founders of Firecrawl",    schema=FoundersSchema,    model="spark-2",    max_credits=100)print(result.data)

Las ejecuciones de agentes son asíncronas. Usa start_agent para obtener un ID de trabajo de inmediato y luego consulta su estado con get_agent_status.

Python

from firecrawl import Firecrawlapp = Firecrawl(api_key="fc-YOUR_API_KEY")# Iniciar una tarea del agenteagent_job = app.start_agent(    prompt="Find the founders of Firecrawl")# Check the statusstatus = app.get_agent_status(agent_job.id)print(status)# Example output:# status='completed'# success=True# data={ ... }# expires_at=datetime.datetime(...)# credits_used=15

Cada ejecución también registra una traza de ejecución y snapshots de salida, que puedes consultar con get_agent_trace y get_agent_snapshot. Consulta Agent para conocer el esquema de eventos y la lista completa de parámetros.

Rastreo de un sitio web con WebSockets#

Para rastrear un sitio web con WebSockets, inicia el trabajo con start_crawl y suscríbete usando el helper watcher. Crea un watcher con el ID del trabajo y adjunta handlers (p. ej., para page, completed, failed) antes de llamar a start().

Python

import asynciofrom firecrawl import AsyncFirecrawlasync def main():    firecrawl = AsyncFirecrawl(api_key="fc-YOUR-API-KEY")    # Iniciar un rastreo primero    started = await firecrawl.start_crawl("https://firecrawl.dev", limit=5)    # Monitorear actualizaciones (snapshots) hasta estado terminal    async for snapshot in firecrawl.watcher(started.id, kind="crawl", poll_interval=2, timeout=120):        if snapshot.status == "completed":            print("COMPLETADO", snapshot.status)            for doc in snapshot.data:                print("DOC", doc.metadata.source_url if doc.metadata else None)        elif snapshot.status == "failed":            print("ERROR", snapshot.status)        else:            print("ESTADO", snapshot.status, snapshot.completed, "/", snapshot.total)asyncio.run(main())

Paginación#

Los puntos de conexión de Firecrawl para crawl y batch scrape devuelven una URL next cuando hay más datos disponibles. El SDK de Python paginá automáticamente por defecto y agrega todos los documentos; en ese caso next será None. Puedes desactivar la paginación automática o establecer límites para controlar el comportamiento de la paginación.

PaginationConfig#

Utiliza PaginationConfig para controlar el comportamiento de la paginación al llamar a get_crawl_status o get_batch_scrape_status:

Python

from firecrawl.v2.types import PaginationConfig

Opción	Tipo	Valor predeterminado	Descripción
`auto_paginate`	`bool`	`True`	Cuando es `True`, obtiene automáticamente todas las páginas y agrupa los resultados. Establécelo en `False` para obtener una página a la vez.
`max_pages`	`int`	`None`	Se detiene después de obtener esta cantidad de páginas (solo se aplica cuando `auto_paginate=True`).
`max_results`	`int`	`None`	Se detiene después de recopilar esta cantidad de documentos (solo se aplica cuando `auto_paginate=True`).
`max_wait_time`	`int`	`None`	Se detiene después de esta cantidad de segundos (solo se aplica cuando `auto_paginate=True`).

Utilidades para paginación manual#

Cuando auto_paginate=False, la respuesta incluye una URL next si hay más datos disponibles. Utiliza estos métodos auxiliares para obtener las páginas siguientes:

get_crawl_status_page(next_url) - Obtiene la siguiente página de resultados de crawl usando la URL opaca next de una respuesta anterior.
get_batch_scrape_status_page(next_url) - Obtiene la siguiente página de resultados de batch scrape usando la URL opaca next de una respuesta anterior.

Estos métodos devuelven el mismo tipo de respuesta que la llamada de estado original, incluida una nueva URL next si quedan más páginas.

Rastreo#

Usa el método auxiliar crawl para la forma más sencilla, o inicia un job y pagina manualmente.

Rastreo simple (paginación automática, por defecto)

Consulta el flujo por defecto en Rastrear un sitio web.

Rastreo manual con control de paginación

Inicia un job y luego recupera una página a la vez con auto_paginate=False. Usa get_crawl_status_page para recuperar las páginas posteriores:

Python

crawl_job = client.start_crawl("https://example.com", limit=100)# Fetch first pagestatus = client.get_crawl_status(    crawl_job.id,    pagination_config=PaginationConfig(auto_paginate=False))print("First page:", len(status.data), "docs")# Obtener páginas siguientes usando get_crawl_status_pagewhile status.next:    status = client.get_crawl_status_page(status.next)    print("Next page:", len(status.data), "docs")

Rastreo manual con límites (paginación automática + detención anticipada)

Mantén la paginación automática activada, pero deténla antes con max_pages, max_results o max_wait_time:

Python

status = client.get_crawl_status(    crawl_job.id,    pagination_config=PaginationConfig(max_pages=2, max_results=50, max_wait_time=15),)print("rastreo limitado:", status.status, "docs:", len(status.data), "siguiente:", status.next)

Extracción por lotes#

Usa el método de espera batch_scrape o inicia un job y pagina manualmente.

Raspado por lotes simple (paginación automática, por defecto)

Consulta el flujo por defecto en Batch Scrape.

Extracción por lotes manual con control de paginación

Inicia un trabajo y luego obtén una página a la vez con auto_paginate=False. Usa get_batch_scrape_status_page para obtener las páginas siguientes:

Python

batch_job = client.start_batch_scrape(urls)# Obtener la primera páginastatus = client.get_batch_scrape_status(    batch_job.id,    pagination_config=PaginationConfig(auto_paginate=False))print("Primera página:", len(status.data), "docs")# Obtener las páginas siguientes usando get_batch_scrape_status_pagewhile status.next:    status = client.get_batch_scrape_status_page(status.next)    print("Siguiente página:", len(status.data), "docs")

Raspado manual por lotes con límites (paginación automática + detención anticipada)

Mantén la paginación automática activada, pero detén antes con max_pages, max_results o max_wait_time:

Python

status = client.get_batch_scrape_status(    batch_job.id,    pagination_config=PaginationConfig(max_pages=2, max_results=100, max_wait_time=20),)print("lote limitado:", status.status, "docs:", len(status.data), "siguiente:", status.next)

Manejo de errores#

Cuando una petición falla, el SDK genera una excepción con un mensaje descriptivo que explica qué salió mal. Encapsula las llamadas en try/except para capturar estas excepciones y manejar los errores en tu aplicación.

Clase asíncrona#

Para operaciones asíncronas, utiliza la clase AsyncFirecrawl. Sus métodos son equivalentes a los de Firecrawl, pero no bloquean el hilo principal.

Python

import asynciofrom firecrawl import AsyncFirecrawlasync def main():    firecrawl = AsyncFirecrawl(api_key="fc-TU-API-KEY")    # Extraer    doc = await firecrawl.scrape("https://firecrawl.dev", formats=["markdown"])  # type: ignore[arg-type]    print(doc.get("markdown"))    # Buscar    results = await firecrawl.search("firecrawl", limit=2)    print(results.get("web", []))    # Rastreo (inicio y estado)    started = await firecrawl.start_crawl("https://docs.firecrawl.dev", limit=3)    status = await firecrawl.get_crawl_status(started.id)    print(status.status)    # Extracción por lotes (en espera)    job = await firecrawl.batch_scrape([        "https://firecrawl.dev",        "https://docs.firecrawl.dev",    ], formats=["markdown"], poll_interval=1, timeout=60)    print(job.status, job.completed, job.total)asyncio.run(main())

Python

from firecrawl import AsyncFirecrawlasync_firecrawl = AsyncFirecrawl(api_key="fc-YOUR-API-KEY")parsed = await async_firecrawl.parse(    b"<!DOCTYPE html><html><body><h1>Async Parse</h1></body></html>",    filename="upload.html",    content_type="text/html",)

Navegador#

Inicia sesiones de navegador en la nube y ejecuta código de forma remota.

Crear una sesión#

Python

from firecrawl import Firecrawlapp = Firecrawl(api_key="fc-YOUR-API-KEY")session = app.browser()print(session.id)             # ID de sesiónprint(session.cdp_url)        # wss://cdp-proxy.firecrawl.dev/cdp/...print(session.live_view_url)  # https://liveview.firecrawl.dev/...

Ejecutar código#

Python

result = app.browser_execute(    session.id,    code='await page.goto("https://news.ycombinator.com")\ntitle = await page.title()\nprint(title)',    language="python",)print(result.result)  # "Hacker News"

Ejecutar JavaScript en lugar de Python:

Python

result = app.browser_execute(    session.id,    code='await page.goto("https://example.com"); const t = await page.title(); console.log(t);',    language="node",)

Perfiles#

Guarda y reutiliza el estado del navegador (cookies, localStorage, etc.) entre sesiones:

Python

session = app.browser(    ttl=600,    profile={        "name": "my-profile",        "save_changes": True,    },)

Conectar vía CDP#

Para tener control total de Playwright, conéctate directamente mediante la URL de CDP:

Python

from playwright.sync_api import sync_playwrightwith sync_playwright() as p:    browser = p.chromium.connect_over_cdp(session.cdp_url)    context = browser.contexts[0]    page = context.pages[0] if context.pages else context.new_page()    page.goto("https://example.com")    print(page.title())    browser.close()

Listar y cerrar sesiones#

Python

# List active sessionssessions = app.list_browsers(status="active")for s in sessions.sessions:    print(s.id, s.status, s.created_at)# Close a sessionapp.delete_browser(session.id)

Sesión interactiva vinculada al scrape#

Usa un ID de trabajo de scrape para seguir interactuando con el contexto de la página reproducida de ese scrape:

interact(job_id, ...) ejecuta código en la sesión de browser vinculada al scrape.
La primera llamada a interact inicializa automáticamente la sesión a partir del contexto del scrape.
Las llamadas adicionales a interact con el mismo ID de trabajo reutilizan ese estado activo del browser.
stop_interaction(job_id) detiene la sesión interactiva cuando hayas terminado.

Python

doc = app.scrape(    "https://example.com",    actions=[{"type": "click", "selector": "a[href='/pricing']"}],)scrape_job_id = doc.metadata_typed.scrape_idif not scrape_job_id:    raise RuntimeError("Missing scrape job id")run = app.interact(    scrape_job_id,    code="print(await page.url())",    language="python",    timeout=60,)print(run.stdout)app.stop_interaction(scrape_job_id)

¿Eres un agente de IA que necesita una clave de API de Firecrawl? Consulta firecrawl.dev/agent-onboarding/SKILL.md para obtener instrucciones de configuración inicial automatizada.