Saltar al contenido principal

​
Instalación

Para instalar el SDK de Python de Firecrawl, puedes usar pip:
Python
# pip install firecrawl-py

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-TU-API-KEY")

​
Uso

  1. Obtén una clave de API en firecrawl.dev
  2. Define la clave de API como una variable de entorno llamada FIRECRAWL_API_KEY o pásala como parámetro a la clase Firecrawl.
Aquí tienes un ejemplo de cómo usar el SDK:
Python
from firecrawl import Firecrawl

firecrawl = 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. Recibe la URL como parámetro y devuelve el documento extraído.
Python
# Extraer un sitio web:
scrape_result = firecrawl.scrape('firecrawl.dev', formats=['markdown', 'html'])
print(scrape_result)

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

​
Iniciar un rastreo

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

​
Comprobar el estado del rastreo

Para comprobar el estado de un job de rastreo, usa el método get_crawl_status. Recibe el ID del job como parámetro y devuelve el estado actual del rastreo.
Python
estado = firecrawl.get_crawl_status("<crawl-id>")
print(estado)

​
Cancelar un rastreo

Para cancelar un trabajo de rastreo, usa el método cancel_crawl. Recibe el ID del trabajo iniciado con start_crawl como parámetro y devuelve 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)

​
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 asyncio
from firecrawl import AsyncFirecrawl

async 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())
Los puntos de conexión de Firecrawl para crawl y batch 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.

​
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)
Rastreo manual con control de paginación (una sola página)
  • Inicia un job y luego obtén una página a la vez con auto_paginate=False.
Python
crawl_job = client.start_crawl("https://example.com", limit=100)

status = client.get_crawl_status(crawl_job.id, pagination_config=PaginationConfig(auto_paginate=False))
print("rastrear una sola página:", status.status, "docs:", len(status.data), "siguiente:", status.next)
Rastreo manual 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_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)
Raspado manual por lotes con control de paginación (una sola página)
  • Inicia un trabajo y luego obtén una página a la vez con auto_paginate=False.
Python
batch_job = client.start_batch_scrape(urls)
status = client.get_batch_scrape_status(batch_job.id, pagination_config=PaginationConfig(auto_paginate=False))
print("lote: una sola página:", status.status, "docs:", len(status.data), "siguiente:", status.next)
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

El SDK gestiona los errores que devuelve la API de Firecrawl y genera las excepciones correspondientes. Si se produce un error durante una solicitud, se lanzará una excepción con un mensaje descriptivo.

​
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 asyncio
from firecrawl import AsyncFirecrawl

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