> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# 批量抓取
> 通过单个批处理作业抓取多个 URL
批量抓取让你能够在单个任务中抓取多个 URL。传入一个 URL 列表和可选参数后，Firecrawl 会并发处理这些 URL，并一次性返回所有结果。
* 类似 `/crawl`，但适用于明确指定的一组 URL
* 支持同步和异步模式
* 支持所有抓取选项，包括结构化提取
* 可为每个任务配置并发数
## 工作方式
你可以通过两种方式运行批量抓取：
| 模式 | SDK 方法 (JS / Python) | 行为 |
| -- | ----------------------------------------- | ---------------------------- |
| 同步 | `batchScrape` / `batch_scrape` | 启动批量任务并等待其完成，返回所有结果 |
| 异步 | `startBatchScrape` / `start_batch_scrape` | 启动批量任务并返回作业 ID，用于轮询或 Webhook |
## 基本用法
```python Python theme={null}
from firecrawl import Firecrawl
firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
# 异步：启动批量任务并立即返回任务 ID
start = firecrawl.start_batch_scrape([
"https://firecrawl.dev",
"https://docs.firecrawl.dev",
], formats=["markdown"])
status = firecrawl.get_batch_scrape_status(start.id)
# 或同步：启动批量任务并等待完成
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 Node theme={null}
import { Firecrawl } from 'firecrawl';
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
// 异步：启动批量任务并立即返回任务 ID
const { id } = await firecrawl.startBatchScrape([
'https://firecrawl.dev',
'https://docs.firecrawl.dev'
], {
options: { formats: ['markdown'] },
});
const status = await firecrawl.getBatchScrapeStatus(id);
// 或同步：启动批量任务并等待完成
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 theme={null}
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"]
}'
```
### 响应
调用 `batchScrape` / `batch_scrape` 会在批处理完成后返回完整结果。
```json 已完成 theme={null}
{
"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": "[Firecrawl 文档首页！[浅色标志](https://mintlify.s3-us-west-1.amazonaws.com/firecrawl/logo/light.svg)!...",
"html": "...",
"metadata": {
"title": "使用 Groq Llama 3 构建“网站对话”功能 | Firecrawl",
"language": "en",
"sourceURL": "https://docs.firecrawl.dev/learn/rag-llama3",
"description": "了解如何使用 Firecrawl、Groq Llama 3 和 LangChain 构建“与你的网站对话”的机器人。",
"ogLocaleAlternate": [],
"statusCode": 200
}
},
...
]
}
```
调用 `startBatchScrape` / `start_batch_scrape` 会返回一个作业 ID。你可以通过 `getBatchScrapeStatus` / `get_batch_scrape_status`、API 端点 `/batch/scrape/{id}`，或 webhooks 来跟踪进度。作业结果在完成后会通过 API 保留 24 小时。在此之后，你仍然可以在[活动日志](https://www.firecrawl.dev/app/logs)中查看批量抓取历史和结果。
```json theme={null}
{
"success": true,
"id": "123-456-789",
"url": "https://api.firecrawl.dev/v2/batch/scrape/123-456-789"
}
```
## 并发
默认情况下，批量抓取作业会使用你团队的全部浏览器并发上限 (参见 [Rate Limits](/zh/rate-limits)) 。你可以通过 `maxConcurrency` 参数为每个作业降低并发数。
例如，`maxConcurrency: 50` 会将该作业限制为最多 50 个同时抓取。对于大批量作业，如果将这个值设得过低，会显著减慢处理速度，因此只有在你需要为其他并发作业预留容量时才应降低它。
你可以使用批量抓取，从该批次中的每个页面提取结构化数据。当你希望对一组 URL 应用相同的 schema 时，这会非常有用。
```python Python theme={null}
from firecrawl import Firecrawl
firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")
# 抓取多个站点：
batch_scrape_result = firecrawl.batch_scrape(
['https://docs.firecrawl.dev', 'https://docs.firecrawl.dev/sdks/overview'],
formats=[{
'type': 'json',
'prompt': '提取页面的标题和描述。',
'schema': {
'type': 'object',
'properties': {
'title': {'type': 'string'},
'description': {'type': 'string'}
},
'required': ['title', 'description']
}
}]
)
print(batch_scrape_result)
# 或者可以使用 start 方法：
batch_scrape_job = firecrawl.start_batch_scrape(
['https://docs.firecrawl.dev', 'https://docs.firecrawl.dev/sdks/overview'],
formats=[{
'type': 'json',
'prompt': '提取页面的标题和描述。',
'schema': {
'type': 'object',
'properties': {
'title': {'type': 'string'},
'description': {'type': 'string'}
},
'required': ['title', 'description']
}
}]
)
print(batch_scrape_job)
# 然后可使用作业 ID 查询批量抓取的状态：
batch_scrape_status = firecrawl.get_batch_scrape_status(batch_scrape_job.id)
print(batch_scrape_status)
```
```js Node theme={null}
import { Firecrawl, ScrapeResponse } from 'firecrawl';
const firecrawl = new Firecrawl({apiKey: "fc-YOUR_API_KEY"});
// 定义用于提取内容的 schema
const schema = {
type: "object",
properties: {
title: { type: "string" },
description: { type: "string" }
},
required: ["title", "description"]
};
// 抓取多个网站（同步）：
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
}
]
});
// 输出本次批量抓取的所有结果：
console.log(batchScrapeResult)
// 或者可以使用 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)
// 然后可使用作业 ID 检查批量抓取的状态：
const batchScrapeStatus = await firecrawl.getBatchScrapeStatus(batchScrapeJob.id);
console.log(batchScrapeStatus)
```
```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/batch/scrape \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"urls": ["https://docs.firecrawl.dev", "https://docs.firecrawl.dev/sdks/overview"],
"formats" : [{
"type": "json",
"prompt": "提取页面的标题和描述。",
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"title",
"description"
]
}
}]
}'
```
### 响应
`batchScrape` / `batch_scrape` 返回完整结果：
```json 已完成 theme={null}
{
"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": [
{
"json": {
"title": "使用 Groq Llama 3 打造“网站聊天”功能 | Firecrawl",
"description": "了解如何结合使用 Firecrawl、Groq Llama 3 和 Langchain，构建一个可与您网站对话的聊天机器人。"
}
},
...
]
}
```
`startBatchScrape` / `start_batch_scrape` 返回任务 ID：
```json theme={null}
{
"success": true,
"id": "123-456-789",
"url": "https://api.firecrawl.dev/v2/batch/scrape/123-456-789"
}
```
## Webhook
你可以配置 Webhook，在批次中的每个 URL 被抓取时接收实时通知。这样你可以立即处理结果，而无需等待整个批次完成。
```bash cURL theme={null}
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": ["started", "page", "completed"]
}
}'
```
### 事件类型
| 事件 | 描述 |
| ------------------------ | ------------- |
| `batch_scrape.started` | 批量抓取任务已开始 |
| `batch_scrape.page` | 单个 URL 已成功抓取 |
| `batch_scrape.completed` | 所有 URL 均已处理完毕 |
| `batch_scrape.failed` | 批量抓取任务遇到错误 |
### 载荷
每次 webhook 投递都包含一个 JSON 请求体，结构如下：
```json theme={null}
{
"success": true,
"type": "batch_scrape.page",
"id": "batch-job-id",
"data": [...],
"metadata": {},
"error": null
}
```
### 验证 webhook 签名
来自 Firecrawl 的每个 webhook 请求都会包含一个 `X-Firecrawl-Signature` 请求头，其中包含一个 HMAC-SHA256 签名。始终验证该签名，以确保 webhook 是真实的且未被篡改。
1. 在你账号设置中的 [Advanced 选项卡](https://www.firecrawl.dev/app/settings?tab=advanced) 获取你的 webhook secret
2. 从 `X-Firecrawl-Signature` 请求头中提取签名
3. 使用你的 secret 对原始请求体计算 HMAC-SHA256
4. 使用时间安全 (timing-safe) 的比较函数将其与签名请求头的值进行比较
切勿在未先验证签名的情况下处理 webhook。`X-Firecrawl-Signature` 请求头中的签名格式为：`sha256=abc123def456...`
如需查看 JavaScript 和 Python 的完整实现示例，请参阅 [Webhook 安全文档](/zh/webhooks/security)。
如需查看更全面的 webhook 文档，包括详细的事件负载、高级配置和故障排查，请参阅 [Webhooks 文档](/zh/webhooks/overview)。
> 你是需要 Firecrawl API 密钥的 AI 代理吗？请参阅 [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) 获取自动化入门说明。