Firecrawl rastreia sites de forma eficiente para extrair dados completos enquanto dribla bloqueios. O processo:
  1. Análise de URL: Examina o sitemap e rastreia o site para identificar links
  2. Navegação: Segue links recursivamente para encontrar todas as subpáginas
  3. Raspagem: Extrai o conteúdo de cada página, lidando com JS e limites de taxa
  4. Saída: Converte os dados em markdown limpo ou em formato estruturado
Isso garante uma coleta abrangente de dados a partir de qualquer URL inicial.

​
Rastreamento

​
endpoint /crawl

Usado para rastrear uma URL e todas as subpáginas acessíveis. Isso cria uma tarefa de rastreamento e retorna um ID para acompanhar o status.
Por padrão, o rastreamento 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 precisar de website.com/other-parent/blog-1, use o parâmetro crawlEntireDomain. Para incluir subdomínios, como blog.website.com ao rastrear website.com, use o parâmetro allowSubdomains.

​
Instalação

# pip install firecrawl-py

from firecrawl import Firecrawl

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

​
Como usar

from firecrawl import Firecrawl

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

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

​
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 raspada pelo crawler: formatos, proxy, cache, ações, localização, tags etc. Veja a lista completa na Referência do endpoint /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, veja abaixo os métodos e 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 crawl

Usado para verificar o status de um job de crawl e obter seu resultado.
Este endpoint só funciona para crawls que estão em andamento ou que foram concluídos recentemente. 
status = firecrawl.get_crawl_status("<crawl-id>")
print(status)

​
Manipulação da resposta

A resposta varia conforme o status do crawl. 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 não estiver presente, isso indica o fim dos dados do crawl. O parâmetro skip define o número máximo de resultados retornados em cada bloco de resultados.
Os parâmetros skip e next só são relevantes 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, ScrapeOptions

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

# Fazer crawl de 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)

# Check the status of the crawl
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")

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

    # Acompanhe as atualizações (snapshots) até o 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.sourceURL 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 Crawl

Você pode configurar webhooks para receber notificações em tempo real conforme o seu crawl avança. Isso permite processar as páginas à medida que são extraídas, em vez de esperar a conclusão de todo o crawl.
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"]
      }
    }'
Para documentação completa sobre webhooks, incluindo tipos de eventos, estrutura do payload e exemplos de implementação, consulte a documentação de Webhooks.

​
Referência rápida

Tipos de evento:
  • crawl.started - Quando o crawl é iniciado
  • crawl.page - Para cada página extraída com sucesso
  • crawl.completed - Quando o crawl é concluído
  • crawl.failed - Se o crawl encontrar um erro
Payload básico: 
{
  "success": true,
  "type": "crawl.page",
  "id": "crawl-job-id",
  "data": [...], // Dados da página para eventos "page"
  "metadata": {}, // Seus metadados personalizados
  "error": null
}
Para ver a configuração detalhada de webhooks, as melhores práticas de segurança e dicas de solução de problemas, acesse a documentação de Webhooks.