Crawlear

O Crawlear envia uma URL ao Firecrawl e descobre e extrai, de forma recursiva, todas as subpáginas acessíveis. Ele lida automaticamente com sitemaps, renderização de JavaScript e limites de taxa, retornando markdown limpo ou dados estruturados para cada página.

Descobre páginas por meio do sitemap e da navegação recursiva por links
Suporta filtragem de caminho, limites de profundidade e controle de subdomínios/links externos
Retorna resultados via polling, WebSocket ou webhook

Experimente no Playground

Teste o rastreamento no playground interativo — sem precisar escrever código.

Instalação

# pip install firecrawl-py

from firecrawl import Firecrawl

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

Uso básico

Envie um trabalho de rastreamento chamando POST /v2/crawl com uma URL inicial. O endpoint retorna um ID do trabalho que você usa para consultar os resultados.

from firecrawl import Firecrawl

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

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

Cada página rastreada consome 1 crédito. O limit padrão de rastreamento é 10.000 páginas. Defina um limit menor para controlar o uso de créditos (por exemplo, limit: 100). São cobrados créditos adicionais para certas opções: modo JSON custa 4 créditos adicionais por página, proxy aprimorado custa 4 créditos adicionais por página, e análise de PDF custa 1 crédito por página de PDF.

Opções de scrape

Todas as opções do endpoint Scrape estão disponíveis no crawl via scrapeOptions (JS) / scrape_options (Python). Elas se aplicam a cada página que o crawler coleta, incluindo formatos, proxy, cache, ações, localização e tags.

from firecrawl import Firecrawl

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

# Crawl com opções de scrape
response = firecrawl.crawl('https://example.com',
    limit=100,
    scrape_options={
        'formats': [
            'markdown',
            { 'type': 'json', 'schema': { 'type': 'object', 'properties': { 'title': { 'type': 'string' } } } }
        ],
        'proxy': 'auto',
        'max_age': 600000,
        'only_main_content': True
    }
)

Verificando o status do rastreamento

Use o ID do job para consultar o status do rastreamento e obter os resultados.

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

Os resultados do job ficam disponíveis via API por 24 horas após a conclusão. Após esse período, você ainda pode ver o histórico e os resultados dos seus rastreamentos nos activity logs.

As páginas no array data dos resultados do rastreamento são páginas que o Firecrawl conseguiu extrair com sucesso, mesmo que o site de destino tenha retornado um erro HTTP como 404. O campo metadata.statusCode mostra o código de status HTTP retornado pelo site de destino. Para recuperar páginas que o próprio Firecrawl não conseguiu extrair (por exemplo, erros de rede, timeouts ou bloqueios por robots.txt), use o endpoint dedicado Get Crawl Errors (GET /crawl/{id}/errors).

Tratamento de respostas

A resposta varia conforme o status da varredura. Para respostas incompletas ou grandes (acima de 10 MB), é fornecido um parâmetro de URL next. Você deve requisitar essa URL para obter os próximos 10 MB de dados. Se o parâmetro next estiver ausente, isso indica o fim dos dados da varredura.

Os parâmetros skip e next são relevantes apenas ao acessar a API diretamente. Se você estiver usando o SDK, a paginação é tratada automaticamente e todos os resultados são retornados de uma vez.

{
  "status": "em andamento",
  "total": 36,
  "completed": 10,
  "creditsUsed": 10,
  "expiresAt": "2024-00-00T00:00:00.000Z",
  "next": "https://api.firecrawl.dev/v2/crawl/123-456-789?skip=10",
  "data": [
    {
      "markdown": "[Página inicial da documentação do Firecrawl![logotipo claro](https://mintlify.s3-us-west-1.amazonaws.com/firecrawl/logo/light.svg)!...",
      "html": "<!DOCTYPE html><html lang=\"en\" class=\"js-focus-visible lg:[--scroll-mt:9.5rem]\" data-js-focus-visible=\"\">...",
      "metadata": {
        "title": "Crie um 'Chat com o site' usando Groq Llama 3 | Firecrawl",
        "language": "en",
        "sourceURL": "https://docs.firecrawl.dev/learn/rag-llama3",
        "description": "Aprenda a usar o Firecrawl, o Groq Llama 3 e o LangChain para criar um bot de 'chat com seu site'."
        "ogLocaleAlternate": [],
        "statusCode": 200
      }
    },
    ...
  ]
}

Métodos do SDK

Existem duas maneiras de usar o crawl com o SDK.

Crawl e aguarde

O método crawl aguarda a conclusão do crawl e retorna a resposta completa. Faz a paginação automaticamente. Isso é recomendado para a maioria dos casos de uso.

from firecrawl import Firecrawl
from firecrawl.types import ScrapeOptions

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

# Rastreie um site:
crawl_status = firecrawl.crawl(
  'https://firecrawl.dev', 
  limit=100, 
  scrape_options=ScrapeOptions(formats=['markdown', 'html']),
  poll_interval=30
)
print(crawl_status)

A resposta inclui o status do crawl e todos os dados extraídos:

success=True
status='concluída'
completed=100
total=100
creditsUsed=100
expiresAt=datetime.datetime(2025, 4, 23, 19, 21, 17, tzinfo=TzInfo(UTC))
next=None
data=[
  Document(
    markdown='[Dia 7 - Launch Week III. Dia de Integrações — 14 a 20 de abril](...',
    metadata={
      'title': '15 projetos de web scraping em Python: do básico ao avançado',
      ...
      'scrapeId': '97dcf796-c09b-43c9-b4f7-868a7a5af722',
      'sourceURL': 'https://www.firecrawl.dev/blog/python-web-scraping-projects',
      'url': 'https://www.firecrawl.dev/blog/python-web-scraping-projects',
      'statusCode': 200
    }
  ),
  ...
]

Inicie e verifique depois

O método startCrawl / start_crawl retorna imediatamente com um ID de crawl. Depois, você verifica o status manualmente. Isso é útil para crawls de longa duração ou lógica de polling personalizada.

from firecrawl import Firecrawl

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

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

# Verifique o status do rastreamento
status = firecrawl.get_crawl_status(job.id)
print(status)

A resposta inicial retorna o ID do job:

{
  "success": true,
  "id": "123-456-789",
  "url": "https://api.firecrawl.dev/v2/crawl/123-456-789"
}

Resultados em tempo real com WebSocket

O método watcher fornece atualizações em tempo real conforme as páginas são rastreadas. Inicie um crawl e, em seguida, assine os eventos para processar os dados imediatamente.

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

Webhooks

Você pode configurar webhooks para receber notificações em tempo real conforme o rastreamento avança. Isso permite processar páginas à medida que são coletadas, em vez de esperar a conclusão de todo o rastreamento.

cURL

curl -X POST https://api.firecrawl.dev/v2/crawl \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "limit": 100,
      "webhook": {
        "url": "https://your-domain.com/webhook",
        "metadata": {
          "any_key": "any_value"
        },
        "events": ["iniciado", "página", "concluído"]
      }
    }'

Tipos de evento

Evento	Descrição
`crawl.started`	Disparado quando o crawl é iniciado
`crawl.page`	Disparado para cada página extraída com sucesso
`crawl.completed`	Disparado quando o crawl é concluído
`crawl.failed`	Disparado se ocorrer um erro durante o crawl

Payload

{
  "success": true,
  "type": "crawl.page",
  "id": "crawl-job-id",
  "data": [...], // Dados da página para eventos 'page'
  "metadata": {}, // Your custom metadata
  "error": null
}

Verificando assinaturas de webhook

Toda requisição de webhook do Firecrawl inclui um cabeçalho X-Firecrawl-Signature contendo uma assinatura HMAC-SHA256. Sempre verifique essa assinatura para garantir que o webhook é autêntico e não foi adulterado.

Obtenha seu segredo de webhook na aba Advanced das configurações da sua conta
Extraia a assinatura do cabeçalho X-Firecrawl-Signature
Calcule o HMAC-SHA256 do corpo bruto da requisição usando o seu segredo
Compare com o cabeçalho de assinatura usando uma função com proteção contra ataques de timing (tempo constante)

Nunca processe um webhook sem verificar sua assinatura primeiro. O cabeçalho X-Firecrawl-Signature contém a assinatura no formato: sha256=abc123def456...

Para exemplos completos de implementação em JavaScript e Python, consulte a documentação de segurança de webhooks. Para a documentação completa sobre webhooks, incluindo payloads detalhados de eventos, estrutura de payload, configuração avançada e solução de problemas, consulte a documentação de Webhooks.

Referência de configuração

O conjunto completo de parâmetros disponíveis ao enviar um trabalho de crawl:

Parâmetro	Tipo	Padrão	Descrição
`url`	`string`	(obrigatório)	A URL inicial a partir da qual o crawl será executado
`limit`	`integer`	`10000`	Número máximo de páginas a rastrear
`maxDiscoveryDepth`	`integer`	(nenhum)	Profundidade máxima a partir da URL raiz com base na ordem de descoberta. O site raiz e as páginas do sitemap têm profundidade de descoberta 0.
`includePaths`	`string[]`	(nenhum)	Padrões regex de pathname de URL a incluir. Apenas os caminhos correspondentes são rastreados.
`excludePaths`	`string[]`	(nenhum)	Padrões regex de pathname de URL a excluir do crawl
`regexOnFullURL`	`boolean`	`false`	Faz a correspondência de `includePaths`/`excludePaths` com a URL completa (incluindo parâmetros de consulta), em vez de apenas o pathname
`crawlEntireDomain`	`boolean`	`false`	Segue links internos para URLs irmãs ou pai, não apenas caminhos filhos
`allowSubdomains`	`boolean`	`false`	Segue links para subdomínios do domínio principal
`allowExternalLinks`	`boolean`	`false`	Segue links para sites externos
`sitemap`	`string`	`"include"`	Tratamento do sitemap: `"include"` (padrão), `"skip"` ou `"only"`
`ignoreQueryParameters`	`boolean`	`false`	Evita raspar novamente o mesmo caminho com parâmetros de consulta diferentes
`delay`	`number`	(nenhum)	Intervalo, em segundos, entre raspagens para respeitar os limites de taxa
`maxConcurrency`	`integer`	(nenhum)	Número máximo de raspagens simultâneas. O padrão é o limite de simultaneidade da sua equipe.
`scrapeOptions`	`object`	(nenhum)	Opções aplicadas a cada página raspada (formatos, proxy, cache, ações etc.)
`webhook`	`object`	(nenhum)	Configuração de webhook para notificações em tempo real
`prompt`	`string`	(nenhum)	Prompt em linguagem natural para gerar opções de crawl. Parâmetros definidos explicitamente substituem os equivalentes gerados.

Detalhes importantes

Por padrão, o crawl ignora sublinks que não são descendentes da URL fornecida. Por exemplo, website.com/other-parent/blog-1 não seria retornada se você fizesse crawl de website.com/blogs/. Use o parâmetro crawlEntireDomain para incluir caminhos irmãos e superiores. Para fazer crawl de subdomínios como blog.website.com ao fazer crawl de website.com, use o parâmetro allowSubdomains.

Descoberta de sitemap: Por padrão, o crawler inclui o sitemap do site para descobrir URLs (sitemap: "include"). Se você definir sitemap: "skip", apenas páginas acessíveis por links HTML a partir da URL raiz serão encontradas. Recursos como PDFs ou páginas em níveis mais profundos, listados no sitemap mas não vinculados diretamente no HTML, não serão encontrados. Para obter a cobertura máxima, mantenha a configuração padrão.
Uso de créditos: Cada página rastreada custa 1 crédito. O modo JSON adiciona 4 créditos por página, o proxy avançado adiciona 4 créditos por página, e a análise de PDF custa 1 crédito por página do PDF.
Expiração dos resultados: Os resultados do job ficam disponíveis via API por 24 horas após a conclusão. Depois disso, consulte os resultados nos logs de atividade.
Erros de crawl: O array data contém as páginas que o Firecrawl extraiu com sucesso. Use o endpoint Get Crawl Errors para recuperar as páginas que falharam devido a erros de rede, timeouts ou bloqueios por robots.txt.

Primeiros passos

Novos recursos

Recursos principais

Guias para desenvolvedores

Webhooks

Casos de uso

Como contribuir

Experimente no Playground

Instalação

Uso básico

Opções de scrape

Verificando o status do rastreamento

Tratamento de respostas

Métodos do SDK

Crawl e aguarde

Inicie e verifique depois

Resultados em tempo real com WebSocket

Webhooks

Tipos de evento

Payload

Verificando assinaturas de webhook

Referência de configuração

Detalhes importantes

Primeiros passos

Novos recursos

Recursos principais

Guias para desenvolvedores

Webhooks

Casos de uso

Como contribuir

Experimente no Playground

​Instalação

​Uso básico

​Opções de scrape

​Verificando o status do rastreamento

​Tratamento de respostas

​Métodos do SDK

​Crawl e aguarde

​Inicie e verifique depois

​Resultados em tempo real com WebSocket

​Webhooks

​Tipos de evento

​Payload

​Verificando assinaturas de webhook

​Referência de configuração

​Detalhes importantes

Instalação

Uso básico

Opções de scrape

Verificando o status do rastreamento

Tratamento de respostas

Métodos do SDK

Crawl e aguarde

Inicie e verifique depois

Resultados em tempo real com WebSocket

Webhooks

Tipos de evento

Payload

Verificando assinaturas de webhook

Referência de configuração

Detalhes importantes