Python - Firecrawl Docs

Instalação#

Para instalar o SDK do Firecrawl para Python, você pode usar o pip:

Python

# pip install firecrawl-pyfrom firecrawl import Firecrawlfirecrawl = 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.

Note

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

Note

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 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 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#

Tip

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)

Executar um agente#

Envie uma tarefa de pesquisa ou extração a um agente usando o método agent. Ele recebe um prompt, um schema opcional para estruturar o resultado e max_credits para limitar o quanto a execução pode gastar.

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="Nome completo do fundador")    role: Optional[str] = Field(None, description="Cargo ou posição")    background: Optional[str] = Field(None, description="Formação profissional")class FoundersSchema(BaseModel):    founders: List[Founder] = Field(description="List of founders")result = app.agent(    prompt="Find the founders of Firecrawl",    schema=FoundersSchema,    model="spark-2",    max_credits=100)print(result.data)

As execuções de agentes são assíncronas. Use start_agent para receber imediatamente um ID do job e, em seguida, consulte seu status com get_agent_status.

Python

from firecrawl import Firecrawlapp = Firecrawl(api_key="fc-YOUR_API_KEY")# Iniciar uma tarefa de 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 execução também registra um rastro de execução e snapshots do resultado, que podem ser acessados com get_agent_trace e get_agent_snapshot. Consulte Agent para ver o schema de eventos e a lista completa de parâmetros.

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 asynciofrom firecrawl import AsyncFirecrawlasync 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 pagestatus = 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_pagewhile 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áginastatus = 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_pagewhile 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 asynciofrom firecrawl import AsyncFirecrawlasync 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 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",)

Browser#

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

Criar sessão#

Python

from firecrawl import Firecrawlapp = Firecrawl(api_key="fc-YOUR-API-KEY")session = app.browser()print(session.id)             # ID da sessãoprint(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_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 & Fechar Sessões#

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)

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

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.