Skip to main content
POST
POST /datasets/v3/trigger 启动异步 Scraper API 采集并返回 snapshot_id。示例按用户名发现 Instagram 个人资料(gd_l1vikfch901nx3by4)。如需在同一响应中获取记录,请以相同的查询参数和请求体调用 POST /datasets/v3/scrape。

请求体

发送带 input 数组的对象: 也接受由输入对象组成的纯 JSON 数组,但无法携带 limit_per_input 或 deliver。

示例中的查询参数

示例未发送 format 参数。

输出格式

Scraper API 的输出格式为 NDJSON(默认)、JSON、JSON lines、CSV 和 Parquet。每种格式都有对应的 API 值,但并非每个值在所有位置都可用: 不带 format 的 /scrape 请求或快照下载返回 NDJSON,每行一条记录。如需 JSON 数组,请设置 format=json。2026 年 9 月 30 日验证。 “未列出”表示该值不在该参数的 API 规范中。NDJSON 和 JSON lines 是两个独立的 API 值:ndjson 和 jsonl。 相关指南:如何使用异步请求批量抓取数据 错误消息与处理方式:Scraper API 错误代码

授权

Authorization
string
header
必填

在 Authorization 头中使用您的 Bright Data API Key 作为 Bearer token。

认证方法:

  1. 从 Bright Data 账户设置获取您的 API Key: https://brightdata.com/cp/setting/users
  2. 在请求的 Authorization 头中包含 API Key
  3. 格式: Authorization: Bearer YOUR_API_KEY

示例:

了解如何获取 Bright Data API Key: https://docs.brightdata.com/cn/api-reference/authentication#如何生成新的-api-key?

查询参数

dataset_id
string
必填

用于触发数据收集的数据集 ID。更多信息请参阅 数据集 ID。

示例:

"gd_l1vikfnt1wgvvqz95w"

custom_output_fields
string

"custom_output_fields" 参数用于筛选响应数据,仅包含指定字段。你可以用管道符 (|) 列出所需输出列。

例如,如果你只希望响应包含 URL 和最后更新时间,可以将参数设置为 "url|about.updated_on"。这允许你自定义数据输出,仅包含与你需求相关的字段。

示例:

"url|about.updated_on"

type
enum<string>

设置为 "discover_new" 以触发包含发现阶段的收集。

启用发现阶段,用于通过搜索、分类或关键词等方式查找新实体或产品。当收集数据时,如果特定目标未知,请使用此选项。它会根据提供的输入发现新信息,而不是使用预定义数据点。

可用选项:
discover_new
discover_by
string

指定收集过程中发现新数据的方法,可用选项如下:

  • keyword:通过关键词发现新实体或产品。例如 "smartphones" - 将触发收集以发现新的智能手机产品或实体。
  • best_sellers_url:使用列出畅销商品的 URL 发现新产品。例如 "https://example.com/best-sellers" - 用于发现网站上的畅销产品。
  • category_url:使用列出类别的 URL 发现该类别下的新实体。例如 "https://example.com/electronics" - 用于发现电子类别下的新产品。
  • location:基于位置发现与该位置相关的实体。例如 "New York" - 将触发收集以发现指定位置相关的数据。
include_errors
boolean

在结果中包含错误报告。将 "include_errors" 设置为 true,可以收到数据收集过程中发生的任何错误的详细报告。

示例:

true

limit_per_input
number

限制每个输入的结果数量。建议在请求体中与 input 并列发送 limit_per_input。该查询参数在 /scrape 和 /trigger 上同样会限制结果数量(2026 年 9 月 30 日验证)。

必填范围: x >= 1
limit_multiple_results
number

限制总结果数量

必填范围: x >= 1
notify
string

指定数据收集任务完成后是否发送通知。设置为 true 时,将向指定的 webhook 发送通知,告知收集状态或完成情况。

示例:

true

endpoint
string

指定用于数据收集过程的 Webhook URL。

示例:

"https://example.com/webhook"

format
enum<string>

投递数据的格式:json、ndjson、jsonl 或 csv。如需下载快照,请在下载请求上设置 format;不设置时下载结果为 NDJSON。如需 Parquet 文件,请投递到存储,并将 deliver.filename.extension 设为 parquet。见输出格式。

可用选项:
json,
ndjson,
jsonl,
csv
示例:

"json"

auth_header
string

Webhook 交付使用的授权头

uncompressed_webhook
boolean

默认情况下,数据将以压缩形式发送。传入 true 可发送未压缩的数据

示例:

true

请求体

发送带 input 数组的对象。也接受由输入对象组成的裸数组。也可以用 CSV 文件上传输入。

一个 input 数组,加上 limit_per_input 等可选字段。

input
object[]
必填

输入对象数组。字段取决于抓取器,例如 url 或 user_name。

示例:
limit_per_input
integer | null

每个输入最多返回的记录数,或 null。适用于结果数量不固定的发现请求。

必填范围: x >= 1
示例:

null

custom_output_fields
string

输出列列表,用 | 分隔(例如,url|about.updated_on)。筛选响应,仅包含指定字段。

示例:

"url|about.updated_on"

响应

收集任务成功启动

snapshot_id
string

Snapshot ID 是特定数据快照的唯一标识符,用于通过 API 触发的数据收集任务获取结果。更多信息请参阅 Snapshot ID。

示例:

"sd_m4x7enmven8djfqak"