Crawlear

Firecrawl rastreia sites com eficiência para extrair dados completos, lidando com infraestrutura web complexa. O processo:

Análise de URL: Examina o sitemap e percorre o site para identificar links
Navegação: Segue links recursivamente para encontrar todas as subpáginas
Extração: Extrai o conteúdo de cada página, lidando com JS e limites de taxa
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")

# npm install @mendable/firecrawl-js

import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({ apiKey: "fc-SUA-CHAVE-API" });

# Instale globalmente com npm
npm install -g firecrawl

# Autentique (configuração única)
firecrawl login

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)

import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({ apiKey: "fc-SUA-CHAVE-API" });

const docs = await firecrawl.crawl('https://docs.firecrawl.dev', { limit: 10 });
console.log(docs);

curl -s -X POST "https://api.firecrawl.dev/v2/crawl" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.firecrawl.dev",
    "limit": 10
  }'

# Inicia um trabalho de crawl (retorna o ID do trabalho)
firecrawl crawl https://firecrawl.dev

# Aguarda a conclusão exibindo o progresso
firecrawl crawl https://firecrawl.dev --wait --progress --limit 100

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,
  },
});

from firecrawl import Firecrawl

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

# Crawl with scrape options
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
    }
)

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)

const status = await firecrawl.getCrawlStatus("<id-da-varredura>");
console.log(status);

# Após iniciar um crawl, consulte o status pelo jobId
curl -s -X GET "https://api.firecrawl.dev/v2/crawl/<jobId>" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

# Verificar o status do crawl usando o ID do job
firecrawl crawl <job-id>

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
      }
    },
    ...
  ]
}

{
  "status": "concluída",
  "total": 36,
  "completed": 36,
  "creditsUsed": 36,
  "expiresAt": "2024-00-00T00:00:00.000Z",
  "next": "https://api.firecrawl.dev/v2/crawl/123-456-789?skip=26",
  "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:

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)

import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({apiKey: "fc-SUA_CHAVE_DE_API"});

const crawlResponse = await firecrawl.crawl('https://firecrawl.dev', {
  limit: 100,
  scrapeOptions: {
    formats: ['markdown', 'html'],
  }
})

console.log(crawlResponse)

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
    }
  ),
  ...
]

{
  success: true,
  status: "completed",
  completed: 100,
  total: 100,
  creditsUsed: 100,
  expiresAt: "2025-04-23T19:28:45.000Z",
  data: [
    {
      markdown: "[Day 7 - Launch Week III.Integrations DayApril ...",
      html: `<!DOCTYPE html><html lang="en" class="light" style="color...`,
      metadata: [Object],
    },
    ...
  ]
}

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)

import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const { id } = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 10 });
console.log(id);

// Verifique o status do crawl
const status = await firecrawl.getCrawlStatus(id);
console.log(status);

curl -s -X POST "https://api.firecrawl.dev/v2/crawl" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.firecrawl.dev",
    "limit": 10
  }'

# Iniciar crawl (assíncrono, retorna o ID do job imediatamente)
firecrawl crawl https://firecrawl.dev --limit 100

# Depois verificar o status
firecrawl crawl <job-id>

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

import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR-API-KEY' });

// Inicie um crawl e depois acompanhe
const { id } = await firecrawl.startCrawl('https://mendable.ai', {
  excludePaths: ['blog/*'],
  limit: 5,
});

const watcher = firecrawl.watcher(id, { kind: 'crawl', pollInterval: 2, timeout: 120 });

watcher.on('document', (doc) => {
  console.log('DOC', doc);
});

watcher.on('error', (err) => {
  console.error('ERR', err?.error || err);
});

watcher.on('done', (state) => {
  console.log('DONE', state.status);
});

// Comece a acompanhar (WS com fallback em HTTP)
await watcher.start();

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:

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.

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.

Primeiros passos

Novos recursos

Recursos principais

Guias para desenvolvedores

Webhooks

Casos de uso

Como contribuir

Experimente no Playground

Rastreamento

endpoint /crawl

Instalação

Uso

Opções de scrape no crawl

Resposta da API

Verificar Job de Rastreamento

Tratamento de respostas

Métodos do SDK

WebSocket de Crawl

Webhook de Rastreamento

Referência rápida

Segurança: Verificando Assinaturas de Webhook

Documentação completa

Experimente no Playground

​Rastreamento

​endpoint /crawl

​Instalação

​Uso

​Opções de scrape no crawl

​Resposta da API

​Verificar Job de Rastreamento

​Tratamento de respostas

​Métodos do SDK

​WebSocket de Crawl

​Webhook de Rastreamento

​Referência rápida

​Segurança: Verificando Assinaturas de Webhook

​Documentação completa

Rastreamento

endpoint /crawl

Instalação

Uso

Opções de scrape no crawl

Resposta da API

Verificar Job de Rastreamento

Tratamento de respostas

Métodos do SDK

WebSocket de Crawl

Webhook de Rastreamento

Referência rápida

Segurança: Verificando Assinaturas de Webhook

Documentação completa