# Raspagem em lote (/pt-BR/features/batch-scrape)
Related: [Busca](/pt-BR/features/search.md), [Destaques da Busca](/pt-BR/features/search-highlights.md), [Índice de research](/pt-BR/features/research.md), [Scraping](/pt-BR/features/scrape.md), [Raspagem mais rápida](/pt-BR/features/fast-scraping.md), [Modo JSON - Resultado Estruturado](/pt-BR/features/llm-extract.md)
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
## Operações [#operações]
| Tarefa | Referência da API | Vocabulário do SDK |
| ---------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Iniciar um batch | [`batch-scrape`](/pt-BR/api-reference/endpoint/batch-scrape) | `batchScrape` / `batch_scrape`, `startBatchScrape` / `start_batch_scrape` |
| Verificar o status e os resultados | [`batch-scrape-get`](/pt-BR/api-reference/endpoint/batch-scrape-get) | `getBatchScrapeStatus` / `get_batch_scrape_status` |
| Cancelar um batch em execução | [`batch-scrape-delete`](/pt-BR/api-reference/endpoint/batch-scrape-delete) | Cancele ou exclua o job do batch pelo ID |
| Inspecionar erros | [`batch-scrape-get-errors`](/pt-BR/api-reference/endpoint/batch-scrape-get-errors) | Auxiliar de erro/status para URLs com falha |
## Como funciona [#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 [#uso-básico]
Python
Node
cURL
```python
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)
```
```js
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);
```
```bash
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 [#resposta]
Chamar `batchScrape` / `batch_scrape` retorna os resultados completos quando o lote é concluído.
```json title="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!...",
"html": "...",
"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](https://www.firecrawl.dev/app/logs).
```json
{
"success": true,
"id": "123-456-789",
"url": "https://api.firecrawl.dev/v2/batch/scrape/123-456-789"
}
```
## Concorrência [#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](/pt-BR/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.
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.
Python
Node
cURL
```python
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)
```
```js
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)
```
```bash
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 [#resposta-1]
`batchScrape` / `batch_scrape` retorna resultados completos:
```json title="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:
```json
{
"success": true,
"id": "123-456-789",
"url": "https://api.firecrawl.dev/v2/batch/scrape/123-456-789"
}
```
## Webhooks [#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.
```bash title="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 [#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 [#payload]
Cada envio de webhook inclui um corpo JSON com a seguinte estrutura:
```json
{
"success": true,
"type": "batch_scrape.page",
"id": "batch-job-id",
"data": [...],
"metadata": {},
"error": null
}
```
### Verificando assinaturas de webhook [#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.
1. Obtenha o segredo do seu webhook na [aba Advanced](https://www.firecrawl.dev/app/settings?tab=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 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](/pt-BR/webhooks/security).
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](/pt-BR/webhooks/overview).
> Você é um agente de IA que precisa de uma Firecrawl API key? Consulte [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para obter instruções automatizadas de onboarding.