​
Instalação

Para instalar o SDK do Firecrawl para Python, você pode usar o pip:
Python
# pip install firecrawl-py

from firecrawl import Firecrawl

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

​
Uso

  1. Obtenha uma chave de API em firecrawl.dev
  2. Configure a chave de API como uma variável de ambiente chamada FIRECRAWL_API_KEY ou passe-a como parâmetro para a classe Firecrawl.
Veja um exemplo de uso do SDK:
Python
from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")

# Fazer scraping de um site:
scrape_status = firecrawl.scrape(
  'https://firecrawl.dev', 
  formats=['markdown', 'html']
)
print(scrape_status)

# Fazer crawling de um site:
crawl_status = firecrawl.crawl(
  'https://firecrawl.dev', 
  limit=100, 
  scrape_options={
    'formats': ['markdown', 'html']
  }
)
print(crawl_status)

​
Extraindo dados de uma URL

Para extrair dados de uma única URL, use o método scrape. Ele recebe a URL como parâmetro e retorna o documento raspado.
Python
# Scrape a website:
scrape_result = firecrawl.scrape('firecrawl.dev', formats=['markdown', 'html'])
print(scrape_result)

​
Rastrear um site

Para rastrear um site, use o método crawl. Ele recebe a URL inicial e, opcionalmente, um objeto de opções. Essas opções permitem definir configurações adicionais para a tarefa de rastreamento, como o número máximo de páginas, os domínios permitidos e o formato de saída. Consulte Paginação para detalhes sobre paginação automática/manual e limites.
Python
job = firecrawl.crawl(url="https://docs.firecrawl.dev", limit=5, poll_interval=1, timeout=120)
print(job)

​
Iniciar um crawl

Prefere não bloquear? Veja a seção Classe assíncrona abaixo.
Inicie uma tarefa sem esperar usando start_crawl. Ela retorna um ID de tarefa que você pode usar para verificar o status. Use crawl quando quiser um aguardador que bloqueia até a conclusão. Consulte Paginação para o comportamento e os limites de paginação.
Python
job = firecrawl.start_crawl(url="https://docs.firecrawl.dev", limit=10)
print(job)

​
Verificando o status do crawl

Para verificar o status de uma tarefa de crawl, use o método get_crawl_status. Ele recebe o ID da tarefa como parâmetro e retorna o status atual do crawl.
Python
status = firecrawl.get_crawl_status("<crawl-id>")
print(status)

​
Cancelando um Crawl

Para cancelar um job de crawl, use o método cancel_crawl. Ele recebe o ID do job do start_crawl como parâmetro e retorna o status do cancelamento.
Python
ok = firecrawl.cancel_crawl("<crawl-id>")
print("Cancelado:", ok)

​
Mapear um site

Use map para gerar uma lista de URLs de um site. As opções permitem personalizar o processo de mapeamento, incluindo excluir subdomínios ou usar o sitemap.
Python
res = firecrawl.map(url="https://firecrawl.dev", limit=10)
print(res)

​
Rastreamento de um site com WebSockets

Para rastrear um site com WebSockets, inicie a tarefa com start_crawl e faça a inscrição usando o helper watcher. Crie um watcher com o ID da tarefa e vincule handlers (por exemplo, para page, completed, failed) antes de chamar start().
Python
import asyncio
from firecrawl import AsyncFirecrawl

async def main():
    firecrawl = AsyncFirecrawl(api_key="fc-YOUR-API-KEY")

    # Primeiro, inicie um crawl
    started = await firecrawl.start_crawl("https://firecrawl.dev", limit=5)

    # Acompanhe as atualizações (snapshots) até o status final
    async for snapshot in firecrawl.watcher(started.id, kind="crawl", poll_interval=2, timeout=120):
        if snapshot.status == "completed":
            print("CONCLUÍDO", snapshot.status)
            for doc in snapshot.data:
                print("DOC", doc.metadata.sourceURL if doc.metadata else None)
        elif snapshot.status == "failed":
            print("ERRO", snapshot.status)
        else:
            print("STATUS", snapshot.status, snapshot.completed, "/", snapshot.total)

asyncio.run(main())
Os endpoints do Firecrawl para crawl e batch retornam uma URL next quando há mais dados disponíveis. O SDK Python pagina automaticamente por padrão e agrega todos os documentos; nesse caso, next será None. Você pode desativar a paginação automática ou definir limites.

​
Crawl

Use o método de espera crawl para a experiência mais simples ou inicie um job e faça a paginação manualmente.
Rastreamento simples (paginação automática, padrão)
Rastreamento manual com controle de paginação (página única)
  • Inicie um job e, em seguida, recupere uma página por vez com 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 página única:", status.status, "docs:", len(status.data), "próximo:", status.next)
Rastreamento manual com limites (paginação automática + interrupção antecipada)
  • Mantenha a paginação automática ativada, mas interrompa antecipadamente com max_pages, max_results ou 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("rastreamento limitado:", status.status, "docs:", len(status.data), "próximo:", status.next)

​
Coleta em lote

Use o método waiter batch_scrape ou inicie um job e faça a paginação manualmente.
Coleta em lote simples (paginação automática, padrão)
Raspagem manual em lote com controle de paginação (página única)
  • Inicie um job e recupere uma página por vez com 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 página única:", status.status, "docs:", len(status.data), "próximo:", status.next)
Coleta manual em lote com limites (paginação automática + parada antecipada)
  • Deixe a paginação automática ativada, mas interrompa antes usando max_pages, max_results ou 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), "próximo:", status.next)

​
Tratamento de erros

O SDK trata os erros retornados pela API do Firecrawl e lança exceções apropriadas. Se ocorrer um erro durante uma requisição, uma exceção será lançada com uma mensagem descritiva.

​
Classe assíncrona

Para operações assíncronas, use a classe AsyncFirecrawl. Seus métodos espelham os de Firecrawl, mas não bloqueiam a thread principal.
Python
import asyncio
from firecrawl import AsyncFirecrawl

async def main():
    firecrawl = AsyncFirecrawl(api_key="fc-YOUR-API-KEY")

    # Extração
    doc = await firecrawl.scrape("https://firecrawl.dev", formats=["markdown"])  # type: ignore[arg-type]
    print(doc.get("markdown"))

    # Busca
    results = await firecrawl.search("firecrawl", limit=2)
    print(results.get("web", []))

    # Rastreamento (início + status)
    started = await firecrawl.start_crawl("https://docs.firecrawl.dev", limit=3)
    status = await firecrawl.get_crawl_status(started.id)
    print(status.status)

    # Extração em lote (aguardando)
    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())