Pular para o conteúdo principal
Firecrawl rastreia sites com eficiência para extrair dados completos, lidando com infraestrutura web complexa. O processo:
  1. Análise de URL: Examina o sitemap e percorre o site para identificar links
  2. Navegação: Segue links recursivamente para encontrar todas as subpáginas
  3. Extração: Extrai o conteúdo de cada página, lidando com JS e limites de taxa
  4. Resultado: Converte os dados em markdown limpo ou em formato estruturado
Isso garante uma coleta abrangente de dados a partir de qualquer URL inicial.

Experimente no Playground

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

​
Rastreamento

​
endpoint /crawl

Usado para rastrear uma URL e todas as subpáginas acessíveis. Isso cria um job de rastreamento e retorna um ID de job para acompanhar o status do rastreamento.
Por padrão, o Crawl ignora sublinks de uma página se eles não forem filhos da URL fornecida. Assim, website.com/other-parent/blog-1 não será retornado se você rastrear website.com/blogs/. Se você quiser website.com/other-parent/blog-1, use o parâmetro crawlEntireDomain. Para rastrear subdomínios como blog.website.com ao rastrear website.com, use o parâmetro allowSubdomains.
Por padrão, o crawler inclui o sitemap do site para descobrir URLs (sitemap: "include"). Se você definir sitemap: "skip", o crawler só encontrará páginas alcançáveis por links HTML a partir da URL raiz. Arquivos como PDFs ou páginas profundamente aninhadas que estejam listadas no sitemap, mas não sejam linkadas diretamente de nenhuma página HTML, serão ignoradas. Para máxima cobertura, mantenha a configuração padrão sitemap: "include".

​
Instalação

# pip install firecrawl-py

from firecrawl import Firecrawl

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

​
Uso

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 no crawl

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: formatos, proxy, cache, ações, localização, tags etc. Veja a lista completa na Referência da API de Scrape. 
import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });

// Crawl with scrape options
const crawlResponse = await firecrawl.crawl('https://example.com', {
  limit: 100,
  scrapeOptions: {
    formats: [
      'markdown',
      {
        type: 'json',
        schema: { type: 'object', properties: { title: { type: 'string' } } },
      },
    ],
    proxy: 'auto',
    maxAge: 600000,
    onlyMainContent: true,
  },
});

​
Resposta da API

Se você estiver usando cURL ou o método starter, será retornado um ID para verificar o status do crawl.
Se você estiver usando o SDK, consulte os métodos abaixo para entender o comportamento de waiter vs starter.
{
  "success": true,
  "id": "123-456-789",
  "url": "https://api.firecrawl.dev/v2/crawl/123-456-789"
}

​
Verificar Job de Rastreamento

Usado para verificar o status de um job de rastreamento e obter seu resultado.
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).
status = firecrawl.get_crawl_status("<crawl-id>")
print(status)

​
Tratamento de respostas

A resposta varia conforme o status da varredura. Para respostas não concluídas 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. O parâmetro skip define o número máximo de resultados retornados em cada bloco.
Os parâmetros skip e next são relevantes apenas ao acessar a API diretamente. Se você estiver usando o SDK, nós cuidamos disso para você e retornaremos todos os resultados 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 SDK:
  1. Crawl e aguarde (crawl):
    • Aguarda a conclusão do crawl e retorna a resposta completa
    • Faz a paginação automaticamente
    • 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
    }
  ),
  ...
]
  1. Inicie e depois verifique o status (startCrawl/start_crawl):
    • Retorna imediatamente com um ID de crawl
    • Permite verificar o status manualmente
    • Ú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)

​
WebSocket de Crawl

O método do Firecrawl baseado em WebSocket, Crawl URL and Watch, permite extrair e monitorar dados em tempo real. Inicie um crawl a partir de uma URL e personalize-o com opções como limite de páginas, domínios permitidos e formatos de saída — ideal para necessidades de processamento de dados imediatas. 
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())

​
Webhook de Rastreamento

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"]
      }
    }'

​
Referência rápida

Tipos de eventos:
  • crawl.started - Quando o rastreamento começa
  • crawl.page - Para cada página rastreada com sucesso
  • crawl.completed - Quando o rastreamento termina
  • crawl.failed - Se o rastreamento encontrar um erro
Payload básico: 
{
  "success": true,
  "type": "crawl.page",
  "id": "crawl-job-id",
  "data": [...], // Dados da página para eventos 'page'
  "metadata": {}, // Your custom metadata
  "error": null
}

​
Segurança: 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. Como funciona:
  1. Obtenha seu segredo de webhook na aba Advanced das configurações da sua conta
  2. Extraia a assinatura do cabeçalho X-Firecrawl-Signature
  3. Calcule o HMAC-SHA256 do corpo bruto da requisição usando o seu segredo
  4. 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.

​
Documentação completa

Para uma documentação completa sobre webhooks, incluindo payloads de eventos detalhados, estrutura do payload, configuração avançada e solução de problemas, consulte a documentação de Webhooks.