curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":[{"user_name":"zoobarcelona"}],"limit_per_input":null}' \
"https://api.brightdata.com/datasets/v3/trigger?dataset_id=gd_l1vikfch901nx3by4¬ify=false&include_errors=true&type=discover_new&discover_by=user_name"
import requests
response = requests.post(
"https://api.brightdata.com/datasets/v3/trigger",
params={
"dataset_id": "gd_l1vikfch901nx3by4",
"notify": "false",
"include_errors": "true",
"type": "discover_new",
"discover_by": "user_name",
},
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"input": [{"user_name": "zoobarcelona"}], "limit_per_input": None},
)
snapshot = response.json()
print("Snapshot ID:", snapshot["snapshot_id"])
import axios from "axios";
const response = await axios.post(
"https://api.brightdata.com/datasets/v3/trigger",
{ input: [{ user_name: "zoobarcelona" }], limit_per_input: null },
{
params: {
dataset_id: "gd_l1vikfch901nx3by4",
notify: false,
include_errors: true,
type: "discover_new",
discover_by: "user_name",
},
headers: { Authorization: "Bearer YOUR_API_KEY" },
}
);
console.log("Snapshot ID:", response.data.snapshot_id);
const params = new URLSearchParams({
dataset_id: "gd_l1vikfch901nx3by4",
notify: "false",
include_errors: "true",
type: "discover_new",
discover_by: "user_name",
});
const response = await fetch(`https://api.brightdata.com/datasets/v3/trigger?${params}`, {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({ input: [{ user_name: "zoobarcelona" }], limit_per_input: null }),
});
const snapshot = await response.json();
console.log("Snapshot ID:", snapshot.snapshot_id);
{
"snapshot_id": "sd_m4x7enmven8djfqak"
}{
"error": "Invalid input provided",
"code": "validation_error",
"type": "validation",
"line": "{\"url\":\"not-a-url\",\"asin\":\"\",\"zipcode\":\"\",\"language\":\"\"}",
"index": 1,
"errors": [
[
"url",
"This field must be a valid url"
]
]
}Invalid credentialsdataset does not exist异步请求
使用 POST /datasets/v3/trigger 触发 Bright Data Scraper API 异步采集,返回用于监控进度和下载结果的快照 ID。
curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":[{"user_name":"zoobarcelona"}],"limit_per_input":null}' \
"https://api.brightdata.com/datasets/v3/trigger?dataset_id=gd_l1vikfch901nx3by4¬ify=false&include_errors=true&type=discover_new&discover_by=user_name"
import requests
response = requests.post(
"https://api.brightdata.com/datasets/v3/trigger",
params={
"dataset_id": "gd_l1vikfch901nx3by4",
"notify": "false",
"include_errors": "true",
"type": "discover_new",
"discover_by": "user_name",
},
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"input": [{"user_name": "zoobarcelona"}], "limit_per_input": None},
)
snapshot = response.json()
print("Snapshot ID:", snapshot["snapshot_id"])
import axios from "axios";
const response = await axios.post(
"https://api.brightdata.com/datasets/v3/trigger",
{ input: [{ user_name: "zoobarcelona" }], limit_per_input: null },
{
params: {
dataset_id: "gd_l1vikfch901nx3by4",
notify: false,
include_errors: true,
type: "discover_new",
discover_by: "user_name",
},
headers: { Authorization: "Bearer YOUR_API_KEY" },
}
);
console.log("Snapshot ID:", response.data.snapshot_id);
const params = new URLSearchParams({
dataset_id: "gd_l1vikfch901nx3by4",
notify: "false",
include_errors: "true",
type: "discover_new",
discover_by: "user_name",
});
const response = await fetch(`https://api.brightdata.com/datasets/v3/trigger?${params}`, {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({ input: [{ user_name: "zoobarcelona" }], limit_per_input: null }),
});
const snapshot = await response.json();
console.log("Snapshot ID:", snapshot.snapshot_id);
{
"snapshot_id": "sd_m4x7enmven8djfqak"
}{
"error": "Invalid input provided",
"code": "validation_error",
"type": "validation",
"line": "{\"url\":\"not-a-url\",\"asin\":\"\",\"zipcode\":\"\",\"language\":\"\"}",
"index": 1,
"errors": [
[
"url",
"This field must be a valid url"
]
]
}Invalid credentialsdataset does not existcurl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":[{"user_name":"zoobarcelona"}],"limit_per_input":null}' \
"https://api.brightdata.com/datasets/v3/trigger?dataset_id=gd_l1vikfch901nx3by4¬ify=false&include_errors=true&type=discover_new&discover_by=user_name"
import requests
response = requests.post(
"https://api.brightdata.com/datasets/v3/trigger",
params={
"dataset_id": "gd_l1vikfch901nx3by4",
"notify": "false",
"include_errors": "true",
"type": "discover_new",
"discover_by": "user_name",
},
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"input": [{"user_name": "zoobarcelona"}], "limit_per_input": None},
)
snapshot = response.json()
print("Snapshot ID:", snapshot["snapshot_id"])
import axios from "axios";
const response = await axios.post(
"https://api.brightdata.com/datasets/v3/trigger",
{ input: [{ user_name: "zoobarcelona" }], limit_per_input: null },
{
params: {
dataset_id: "gd_l1vikfch901nx3by4",
notify: false,
include_errors: true,
type: "discover_new",
discover_by: "user_name",
},
headers: { Authorization: "Bearer YOUR_API_KEY" },
}
);
console.log("Snapshot ID:", response.data.snapshot_id);
const params = new URLSearchParams({
dataset_id: "gd_l1vikfch901nx3by4",
notify: "false",
include_errors: "true",
type: "discover_new",
discover_by: "user_name",
});
const response = await fetch(`https://api.brightdata.com/datasets/v3/trigger?${params}`, {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({ input: [{ user_name: "zoobarcelona" }], limit_per_input: null }),
});
const snapshot = await response.json();
console.log("Snapshot ID:", snapshot.snapshot_id);
POST /datasets/v3/trigger 启动异步 Scraper API 采集并返回 snapshot_id。示例按用户名发现 Instagram 个人资料(gd_l1vikfch901nx3by4)。如需在同一响应中获取记录,请以相同的查询参数和请求体调用 POST /datasets/v3/scrape。
请求体
发送带input 数组的对象:
| 字段 | 类型 | 说明 |
|---|---|---|
input | 对象数组,必填 | 要抓取的输入。字段取决于抓取器,例如 url 或 user_name |
limit_per_input | 整数或 null | 每个输入最多返回的记录数,或 null |
deliver | 对象 | 此任务的投递目标。见投递 Scraper API 结果 |
limit_per_input 或 deliver。
示例中的查询参数
| 参数 | 示例中的值 | 说明 |
|---|---|---|
dataset_id | gd_l1vikfch901nx3by4 | 要运行的抓取器 |
notify | false | 是否发送完成通知 |
include_errors | true | 在结果中包含错误记录 |
type | discover_new | 仅限发现型抓取器 |
discover_by | user_name | 仅限发现型抓取器。发现方式因抓取器而异 |
format 参数。
输出格式
Scraper API 的输出格式为 NDJSON(默认)、JSON、JSON lines、CSV 和 Parquet。每种格式都有对应的 API 值,但并非每个值在所有位置都可用:| 格式 | API 值 | /scrape 的 format | /trigger 的 format | deliver.filename.extension |
|---|---|---|---|---|
| NDJSON(默认) | ndjson | 是 | 是 | 是 |
| JSON | json | 是 | 是 | 是 |
| JSON lines | jsonl | 是 | 是 | 是 |
| CSV | csv | 是 | 是 | 是 |
| Parquet | parquet | 未列出 | 未列出 | 是 |
format 的 /scrape 请求或快照下载返回 NDJSON,每行一条记录。如需 JSON 数组,请设置 format=json。2026 年 9 月 30 日验证。
“未列出”表示该值不在该参数的 API 规范中。NDJSON 和 JSON lines 是两个独立的 API 值:ndjson 和 jsonl。
相关指南:如何使用异步请求批量抓取数据
错误消息与处理方式:Scraper API 错误代码授权
在 Authorization 头中使用您的 Bright Data API Key 作为 Bearer token。
认证方法:
- 从 Bright Data 账户设置获取您的 API Key: https://brightdata.com/cp/setting/users
- 在请求的 Authorization 头中包含 API Key
- 格式:
Authorization: Bearer YOUR_API_KEY
示例:
Authorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df
了解如何获取 Bright Data API Key: https://docs.brightdata.com/cn/api-reference/authentication#如何生成新的-api-key?
查询参数
"custom_output_fields" 参数用于筛选响应数据,仅包含指定字段。你可以用管道符 (|) 列出所需输出列。
例如,如果你只希望响应包含 URL 和最后更新时间,可以将参数设置为 "url|about.updated_on"。这允许你自定义数据输出,仅包含与你需求相关的字段。
"url|about.updated_on"
设置为 "discover_new" 以触发包含发现阶段的收集。
启用发现阶段,用于通过搜索、分类或关键词等方式查找新实体或产品。当收集数据时,如果特定目标未知,请使用此选项。它会根据提供的输入发现新信息,而不是使用预定义数据点。
discover_new 指定收集过程中发现新数据的方法,可用选项如下:
keyword:通过关键词发现新实体或产品。例如 "smartphones" - 将触发收集以发现新的智能手机产品或实体。best_sellers_url:使用列出畅销商品的 URL 发现新产品。例如 "https://example.com/best-sellers" - 用于发现网站上的畅销产品。category_url:使用列出类别的 URL 发现该类别下的新实体。例如 "https://example.com/electronics" - 用于发现电子类别下的新产品。location:基于位置发现与该位置相关的实体。例如 "New York" - 将触发收集以发现指定位置相关的数据。
在结果中包含错误报告。将 "include_errors" 设置为 true,可以收到数据收集过程中发生的任何错误的详细报告。
true
限制每个输入的结果数量。建议在请求体中与 input 并列发送 limit_per_input。该查询参数在 /scrape 和 /trigger 上同样会限制结果数量(2026 年 9 月 30 日验证)。
x >= 1限制总结果数量
x >= 1指定数据收集任务完成后是否发送通知。设置为 true 时,将向指定的 webhook 发送通知,告知收集状态或完成情况。
true
指定用于数据收集过程的 Webhook URL。
"https://example.com/webhook"
Webhook 交付使用的授权头
默认情况下,数据将以压缩形式发送。传入 true 可发送未压缩的数据
true
请求体
发送带 input 数组的对象。也接受由输入对象组成的裸数组。也可以用 CSV 文件上传输入。
- 带 input 的对象 · object
- 裸数组(同样接受) · object[]
一个 input 数组,加上 limit_per_input 等可选字段。
输入对象数组。字段取决于抓取器,例如 url 或 user_name。
Show child attributes
Show child attributes
[ { "url": "https://www.airbnb.com/rooms/50122531" }, { "url": "https://www.airbnb.com/rooms/50127677" } ]
每个输入最多返回的记录数,或 null。适用于结果数量不固定的发现请求。
x >= 1null
输出列列表,用 | 分隔(例如,url|about.updated_on)。筛选响应,仅包含指定字段。
"url|about.updated_on"
响应
收集任务成功启动
Snapshot ID 是特定数据快照的唯一标识符,用于通过 API 触发的数据收集任务获取结果。更多信息请参阅 Snapshot ID。
"sd_m4x7enmven8djfqak"
此页面对您有帮助吗?