Raspagem em lote | Firecrawl

A raspagem em lote permite raspar várias URLs em uma única tarefa. Passe uma lista de URLs e parâmetros opcionais, e o Firecrawl as processa simultaneamente e retorna todos os resultados de uma só vez.

Funciona como /crawl, mas para uma lista explícita de URLs
Modos síncrono e assíncrono
Suporta todas as opções de raspagem, incluindo extração estruturada
Concorrência configurável por tarefa

Como funciona

Você pode executar um scrape em lote de duas formas:

Modo	Método do SDK (JS / Python)	Comportamento
Síncrono	`batchScrape` / `batch_scrape`	Inicia o lote e aguarda a conclusão, retornando todos os resultados
Assíncrono	`startBatchScrape` / `start_batch_scrape`	Inicia o lote e retorna um ID do job para consulta por polling ou webhooks

Uso básico

from firecrawl import Firecrawl

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

# Assíncrono: inicia o batch e retorna um ID do job imediatamente
start = firecrawl.start_batch_scrape([
    "https://firecrawl.dev",
    "https://docs.firecrawl.dev",
], formats=["markdown"])

status = firecrawl.get_batch_scrape_status(start.id)

# Ou síncrono: inicia o batch e aguarda a conclusão
job = firecrawl.batch_scrape([
    "https://firecrawl.dev",
    "https://docs.firecrawl.dev",
], formats=["markdown"], poll_interval=2, wait_timeout=120)

print(job.status, job.completed, job.total)

import { Firecrawl } from 'firecrawl';

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

// Assíncrono: inicia o lote e retorna um ID do job imediatamente
const { id } = await firecrawl.startBatchScrape([
  'https://firecrawl.dev',
  'https://docs.firecrawl.dev'
], {
  options: { formats: ['markdown'] },
});

const status = await firecrawl.getBatchScrapeStatus(id);

// Ou síncrono: inicia o lote e aguarda até concluir
const job = await firecrawl.batchScrape([
  'https://firecrawl.dev',
  'https://docs.firecrawl.dev'
], { options: { formats: ['markdown'] }, pollInterval: 2, timeout: 120 });

console.log(job.status, job.completed, job.total);

curl -s -X POST "https://api.firecrawl.dev/v2/batch/scrape" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://firecrawl.dev", "https://docs.firecrawl.dev"],
    "formats": ["markdown"]
  }'

Resposta

Chamar batchScrape / batch_scrape retorna os resultados completos quando o lote é concluído.

Concluído

{
  "status": "completed",
  "total": 36,
  "completed": 36,
  "creditsUsed": 36,
  "expiresAt": "2024-00-00T00:00:00.000Z",
  "next": "https://api.firecrawl.dev/v2/batch/scrape/123-456-789?skip=26",
  "data": [
    {
      "markdown": "[Página inicial da documentação do Firecrawl![logo 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 o seu site’."
        "ogLocaleAlternate": [],
        "statusCode": 200
      }
    },
    ...
  ]
}

Chamar startBatchScrape / start_batch_scrape retorna um ID de job que você pode acompanhar via getBatchScrapeStatus / get_batch_scrape_status, o endpoint da API /batch/scrape/{id} ou webhooks. Os resultados do job ficam disponíveis via API por 24 horas após a conclusão. Depois desse período, você ainda pode visualizar o histórico e os resultados dos seus batch scrapes nos activity logs.

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

Concorrência

Por padrão, uma tarefa de raspagem em lote usa todo o limite de navegadores simultâneos da sua equipe (consulte Rate Limits). Você pode reduzir isso por tarefa com o parâmetro maxConcurrency. Por exemplo, maxConcurrency: 50 limita essa tarefa a 50 raspagens simultâneas. Definir esse valor muito baixo em lotes grandes vai tornar o processamento significativamente mais lento, então só o reduza se você realmente precisar deixar capacidade para outras tarefas em execução simultânea.

Extração estruturada

Você pode usar a coleta em lote para extrair dados estruturados de cada página do lote. Isso é útil quando você quer aplicar o mesmo esquema a uma lista de URLs.

from firecrawl import Firecrawl

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

# Raspar vários sites:
batch_scrape_result = firecrawl.batch_scrape(
    ['https://docs.firecrawl.dev', 'https://docs.firecrawl.dev/sdks/overview'], 
    formats=[{
        'type': 'json',
        'prompt': 'Extraia o título e a descrição da página.',
        'schema': {
            'type': 'object',
            'properties': {
                'title': {'type': 'string'},
                'description': {'type': 'string'}
            },
            'required': ['title', 'description']
        }
    }]
)
print(batch_scrape_result)

# Ou você pode usar o método start:
batch_scrape_job = firecrawl.start_batch_scrape(
    ['https://docs.firecrawl.dev', 'https://docs.firecrawl.dev/sdks/overview'], 
    formats=[{
        'type': 'json',
        'prompt': 'Extraia o título e a descrição da página.',
        'schema': {
            'type': 'object',
            'properties': {
                'title': {'type': 'string'},
                'description': {'type': 'string'}
            },
            'required': ['title', 'description']
        }
    }]
)
print(batch_scrape_job)

# Em seguida, você pode usar o ID do job para verificar o status da raspagem em lote:
batch_scrape_status = firecrawl.get_batch_scrape_status(batch_scrape_job.id)
print(batch_scrape_status)

import { Firecrawl, ScrapeResponse } from 'firecrawl';

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

// Defina o schema para extrair o conteúdo
const schema = {
  type: "object",
  properties: {
    title: { type: "string" },
    description: { type: "string" }
  },
  required: ["title", "description"]
};

// Raspar vários sites (síncrono):
const batchScrapeResult = await firecrawl.batchScrape(['https://docs.firecrawl.dev', 'https://docs.firecrawl.dev/sdks/overview'], { 
  formats: [
    {
      type: "json",
      prompt: "Extract the title and description from the page.",
      schema: schema
    }
  ]
});

// Exiba todos os resultados da raspagem em lote:
console.log(batchScrapeResult)

// Ou você pode usar o método start:
const batchScrapeJob = await firecrawl.startBatchScrape(['https://docs.firecrawl.dev', 'https://docs.firecrawl.dev/sdks/overview'], { 
  formats: [
    {
      type: "json",
      prompt: "Extract the title and description from the page.",
      schema: schema
    }
  ]
});
console.log(batchScrapeJob)

// Em seguida, use o ID do job para verificar o status da raspagem em lote:
const batchScrapeStatus = await firecrawl.getBatchScrapeStatus(batchScrapeJob.id);
console.log(batchScrapeStatus)

curl -X POST https://api.firecrawl.dev/v2/batch/scrape \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer SEU_TOKEN_DE_API' \
    -d '{
      "urls": ["https://docs.firecrawl.dev", "https://docs.firecrawl.dev/sdks/overview"],
      "formats" : [{
        "type": "json",
        "prompt": "Extraia o título e a descrição da página.",
        "schema": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string"
            },
            "description": {
              "type": "string"
            }
          },
          "required": [
            "title",
            "description"
          ]
        }
      }]
    }'

Resposta

batchScrape / batch_scrape retorna resultados completos:

Concluído

{
  "status": "concluído",
  "total": 36,
  "completed": 36,
  "creditsUsed": 36,
  "expiresAt": "2024-00-00T00:00:00.000Z",
  "next": "https://api.firecrawl.dev/v2/batch/scrape/123-456-789?skip=26",
  "data": [
    {
      "json": {
        "title": "Crie um 'chat com o site' usando Groq Llama 3 | Firecrawl",
        "description": "Aprenda a usar Firecrawl, Groq Llama 3 e LangChain para criar um bot de 'chat com o seu site'."
      }
    },
    ...
  ]
}

startBatchScrape / start_batch_scrape retorna um ID de tarefa:

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

Webhooks

Você pode configurar webhooks para receber notificações em tempo real conforme cada URL do seu lote é raspada. Isso permite processar os resultados imediatamente, em vez de esperar a conclusão de todo o lote.

cURL

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

Tipos de evento

Evento	Descrição
`batch_scrape.started`	O job de raspagem em lote foi iniciado
`batch_scrape.page`	Uma única URL foi raspada com sucesso
`batch_scrape.completed`	Todas as URLs foram processadas
`batch_scrape.failed`	O job de raspagem em lote encontrou um erro

Payload

Cada envio de webhook inclui um corpo JSON com a seguinte estrutura:

{
  "success": true,
  "type": "batch_scrape.page",
  "id": "batch-job-id",
  "data": [...],
  "metadata": {},
  "error": null
}

Verificando assinaturas de webhook

Toda requisição de webhook do Firecrawl inclui o 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 o segredo do seu 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 segura contra ataques de timing

Nunca processe um webhook sem verificar sua assinatura antes. 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 uma documentação abrangente sobre webhooks, incluindo payloads detalhados de eventos, configuração avançada e solução de problemas, consulte a documentação de Webhooks.

Você é um agente de IA que precisa de uma Firecrawl API key? Consulte firecrawl.dev/agent-onboarding/SKILL.md para obter instruções automatizadas de onboarding.

​Como funciona

​Uso básico

​Resposta

​Concorrência

​Extração estruturada

​Resposta

​Webhooks

​Tipos de evento

​Payload

​Verificando assinaturas de webhook

Como funciona

Uso básico

Resposta

Concorrência

Extração estruturada

Resposta

Webhooks

Tipos de evento

Payload

Verificando assinaturas de webhook