SDK Python | Firecrawl

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(
  # Nenhuma API key necessária para começar — adicione uma para limites de taxa mais altos:
  # api_key="fc-YOUR-API-KEY",
)

Uso

Obtenha uma chave de API em firecrawl.dev e, em seguida, configure-a como uma variável de ambiente chamada FIRECRAWL_API_KEY ou passe-a diretamente para a classe Firecrawl.

Sem chave de API? Você pode instanciar Firecrawl sem uma chave e usar scrape, search e interact no plano Free sem chave (com limite de taxa por IP — consulte Limites de taxa). Todos os outros métodos exigem uma chave.

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)

Fazendo scraping de uma URL

Faça scraping de uma única URL com o método scrape. Ele retorna o conteúdo da página como dados estruturados, incluindo markdown, metadados e quaisquer outros formatos que você solicitar.

Python

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

O SDK de Python converte todos os nomes dos campos da resposta de camelCase para snake_case. Por exemplo, campos de metadados como ogImage, ogTitle e sourceURL da API se tornam og_image, og_title e source_url na resposta do SDK.

Análise de arquivos carregados

Use parse para fazer upload de arquivos locais (html, pdf, docx, xlsx, etc.) diretamente para /v2/parse. parse não oferece suporte a changeTracking nem a opções disponíveis apenas no navegador, como actions, wait_for, location, mobile, screenshot e branding.

Python

from firecrawl.v2.types import ParseOptions

parsed = 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 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)

Rastreamento Apenas do Sitemap

Use sitemap="only" para rastrear apenas as URLs do sitemap (a URL inicial é sempre incluída e a descoberta de links em HTML é ignorada).

Python

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

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 rastreamento

Consulte o status de um job de rastreamento com get_crawl_status. Informe o ID do job e receba o status atual junto com os resultados coletados até o momento.

Python

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

Cancelando um Rastreamento

Cancele um job de rastreamento com o método cancel_crawl. Passe o ID do job retornado por start_crawl para receber 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")

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

    # Monitora atualizações (snapshots) até 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.source_url 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())

Paginação

Os endpoints do Firecrawl para crawl e batch scrape 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 para controlar o comportamento da paginação.

PaginationConfig

Use PaginationConfig para controlar o comportamento da paginação ao chamar get_crawl_status ou get_batch_scrape_status:

Python

from firecrawl.v2.types import PaginationConfig

Option	Type	Default	Description
`auto_paginate`	`bool`	`True`	Quando definido como `True`, busca automaticamente todas as páginas e agrega os resultados. Defina como `False` para buscar uma página por vez.
`max_pages`	`int`	`None`	Encerra após buscar esse número de páginas (aplica-se somente quando `auto_paginate=True`).
`max_results`	`int`	`None`	Encerra após coletar esse número de documentos (aplica-se somente quando `auto_paginate=True`).
`max_wait_time`	`int`	`None`	Encerra após esse número de segundos (aplica-se somente quando `auto_paginate=True`).

Auxiliares para Paginação Manual

Quando auto_paginate=False, a resposta inclui uma URL next se houver mais dados disponíveis. Use estes métodos auxiliares para obter as páginas subsequentes:

get_crawl_status_page(next_url) - Obtém a próxima página de resultados de crawl usando a URL next opaca de uma resposta anterior.
get_batch_scrape_status_page(next_url) - Obtém a próxima página de resultados de batch scrape usando a URL next opaca de uma resposta anterior.

Esses métodos retornam o mesmo tipo de resposta da chamada de status original, incluindo uma nova URL next se restarem mais páginas.

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)

Veja o fluxo padrão em Rastrear um site.

Rastreamento manual com controle de paginação

Inicie um job e, em seguida, recupere uma página por vez com auto_paginate=False. Use get_crawl_status_page para recuperar as páginas subsequentes:

Python

crawl_job = client.start_crawl("https://example.com", limit=100)

# Fetch first page
status = client.get_crawl_status(
    crawl_job.id,
    pagination_config=PaginationConfig(auto_paginate=False)
)
print("First page:", len(status.data), "docs")

# Busca páginas subsequentes usando get_crawl_status_page
while status.next:
    status = client.get_crawl_status_page(status.next)
    print("Next page:", len(status.data), "docs")

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)

Veja o fluxo padrão em Coleta em Lote.

Raspagem em lote manual com controle de paginação

Inicie um job e, em seguida, recupere uma página por vez com auto_paginate=False. Use get_batch_scrape_status_page para obter as páginas subsequentes:

Python

batch_job = client.start_batch_scrape(urls)

# Buscar primeira página
status = client.get_batch_scrape_status(
    batch_job.id,
    pagination_config=PaginationConfig(auto_paginate=False)
)
print("Primeira página:", len(status.data), "docs")

# Buscar páginas subsequentes usando get_batch_scrape_status_page
while status.next:
    status = client.get_batch_scrape_status_page(status.next)
    print("Próxima página:", len(status.data), "docs")

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

Quando uma requisição falha, o SDK lança uma exceção com uma mensagem descritiva explicando o que deu errado. Coloque as chamadas em try/except para capturar essas exceções e tratar as falhas na sua aplicação.

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

Python

from firecrawl import AsyncFirecrawl

async_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",
)

Browser

Inicie sessões de navegador na nuvem e execute código remotamente.

Criar sessão

Python

from firecrawl import Firecrawl

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

session = app.browser()
print(session.id)             # ID da sessão
print(session.cdp_url)        # wss://cdp-proxy.firecrawl.dev/cdp/...
print(session.live_view_url)  # https://liveview.firecrawl.dev/...

Executar 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"

Execute JavaScript em vez 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",
)

Perfis

Salve e reutilize o estado do navegador (cookies, localStorage, etc.) em várias sessões:

Python

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

Conectar via CDP

Para ter controle total do Playwright, conecte-se diretamente usando a URL do CDP:

Python

from playwright.sync_api import sync_playwright

with 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 & Fechar Sessões

Python

# List active sessions
sessions = app.list_browsers(status="active")
for s in sessions.sessions:
    print(s.id, s.status, s.created_at)

# Close a session
app.delete_browser(session.id)

Sessão interativa vinculada ao scraping

Use um ID do job de scraping para continuar interagindo com o contexto da página reproduzida a partir desse scraping:

interact(job_id, ...) executa código na sessão do navegador vinculada ao scraping.
A primeira chamada de interact inicializa automaticamente a sessão com base no contexto do scraping.
Chamadas adicionais de interact no mesmo ID do job reutilizam esse estado ativo do navegador.
stop_interaction(job_id) encerra a sessão interativa quando você terminar.

Python

doc = app.scrape(
    "https://example.com",
    actions=[{"type": "click", "selector": "a[href='/pricing']"}],
)

scrape_job_id = doc.metadata_typed.scrape_id
if 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)

Você é um agente de IA que precisa de uma chave de API do Firecrawl? Consulte firecrawl.dev/agent-onboarding/SKILL.md para ver instruções de configuração automatizada.

​Instalação

​Uso

​Fazendo scraping de uma URL

​Análise de arquivos carregados

​Rastrear um site

​Rastreamento Apenas do Sitemap

​Iniciar um crawl

​Verificando o status do rastreamento

​Cancelando um Rastreamento

​Mapear um site

​Rastreamento de um site com WebSockets

​Paginação

​PaginationConfig

​Auxiliares para Paginação Manual

​Crawl

Rastreamento simples (paginação automática, padrão)

Rastreamento manual com controle de paginação

Rastreamento manual com limites (paginação automática + interrupção antecipada)

​Coleta em lote

Coleta em lote simples (paginação automática, padrão)

Raspagem em lote manual com controle de paginação

Coleta manual em lote com limites (paginação automática + parada antecipada)

​Tratamento de erros

​Classe assíncrona

​Browser

​Criar sessão

​Executar código

​Perfis

​Conectar via CDP

​Listar & Fechar Sessões

​Sessão interativa vinculada ao scraping

Instalação

Uso

Fazendo scraping de uma URL

Análise de arquivos carregados

Rastrear um site

Rastreamento Apenas do Sitemap

Iniciar um crawl

Verificando o status do rastreamento

Cancelando um Rastreamento

Mapear um site

Rastreamento de um site com WebSockets

Paginação

PaginationConfig

Auxiliares para Paginação Manual

Crawl

Coleta em lote

Tratamento de erros

Classe assíncrona

Browser

Criar sessão

Executar código

Perfis

Conectar via CDP

Listar & Fechar Sessões

Sessão interativa vinculada ao scraping