同步请求

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/scrape?dataset_id=gd_l1vikfch901nx3by4&notify=false&include_errors=true&type=discover_new&discover_by=user_name"

import requests

response = requests.post(
    "https://api.brightdata.com/datasets/v3/scrape",
    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},
)

print(response.status_code, response.json())

import axios from "axios";

const response = await axios.post(
  "https://api.brightdata.com/datasets/v3/scrape",
  { 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(response.status, response.data);

OK

{
  "snapshot_id": "s_xxx",
  "message": "您的请求仍在处理中，无法在此调用中检索。请使用提供的 Snapshot ID 通过监控快照端点跟踪进度，并在准备好后通过下载快照端点获取数据。"
}

{
  "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 credentials

dataset does not exist

POST

datasets

scrape

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/scrape?dataset_id=gd_l1vikfch901nx3by4&notify=false&include_errors=true&type=discover_new&discover_by=user_name"

import requests

response = requests.post(
    "https://api.brightdata.com/datasets/v3/scrape",
    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},
)

print(response.status_code, response.json())

import axios from "axios";

const response = await axios.post(
  "https://api.brightdata.com/datasets/v3/scrape",
  { 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(response.status, response.data);

OK

{
  "snapshot_id": "s_xxx",
  "message": "您的请求仍在处理中，无法在此调用中检索。请使用提供的 Snapshot ID 通过监控快照端点跟踪进度，并在准备好后通过下载快照端点获取数据。"
}

{
  "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 credentials

dataset does not exist

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/scrape?dataset_id=gd_l1vikfch901nx3by4&notify=false&include_errors=true&type=discover_new&discover_by=user_name"

import requests

response = requests.post(
    "https://api.brightdata.com/datasets/v3/scrape",
    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},
)

print(response.status_code, response.json())

import axios from "axios";

const response = await axios.post(
  "https://api.brightdata.com/datasets/v3/scrape",
  { 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(response.status, response.data);

工作原理

此同步 API 端点允许用户在发送抓取请求时，实时直接在响应中获取结果，例如在终端或应用程序中，无需外部存储或手动下载。此方式通过消除额外的结果获取步骤，使数据采集过程更加高效。使用 format 查询参数设置输出格式。如果未提供格式，响应为 NDJSON，每行一条记录。如需 JSON 数组，请设置 format=json。

请求体

以带 input 数组的对象发送输入：

{
  "input": [{"user_name": "zoobarcelona"}],
  "limit_per_input": null
}

字段	类型	说明
`input`	对象数组，必填	要抓取的输入。字段取决于抓取器，例如 `url` 或 `user_name`
`limit_per_input`	整数或 `null`	每个输入最多返回的记录数，或 `null`
`custom_output_fields`	字符串	要保留的输出字段，用 `\|` 分隔，例如 `title\|final_price\|url`

limit_per_input 对发现请求尤为重要，因为其结果数量不固定。以下请求发现某个子版块中的帖子，并在三条后停止：

{
  "input": [{"url": "https://www.reddit.com/r/learnpython/"}],
  "limit_per_input": 3
}

在查询字符串中附加 type=discover_new&discover_by=subreddit_url 发送。请将 limit_per_input 放在请求体中，与 input 并列。作为查询参数传入的 limit_per_input 同样会限制结果数量（2026 年 9 月 30 日验证），但建议放在请求体中。也接受由输入对象组成的纯 JSON 数组，返回的记录相同，但无法携带 limit_per_input 或 custom_output_fields：

[{"url": "https://www.amazon.com/dp/B0FQFB8FMG"}]

POST /datasets/v3/trigger 接受相同的对象请求体。在该端点上，deliver 配置也放在该对象中。详见异步请求。

超时限制

请注意，此同步请求受 1 分钟超时限制。如果数据获取过程超过此限制，API 将返回 HTTP 202 响应，表示请求仍在处理中。在这种情况下，你将收到一个快照 ID，可通过“监控快照（Monitor Snapshot）”和“下载快照（Download Snapshot）”端点以异步方式监控并获取结果。Bright Data 建议每个 /scrape 请求只发送一个输入，因为输入越多，越难在 1 分钟内完成。202 响应带有 retry-after 头（撰写本文时为 10 秒），指示轮询前应等待的时间。超时情况下的示例响应：

202

{
  "snapshot_id": "sd_m1a2b3c4d5e6f7g8h",
  "message": "Your request is still in progress and cannot be retrieved in this call. Use the provided Snapshot ID to track progress via the Monitor Snapshot endpoint and download it once ready via the Download Snapshot endpoint."
}

如何处理 202 响应

运行超过 1 分钟的 /scrape 请求会返回 HTTP 202 和 snapshot_id，而不是记录，任务继续在后台运行。请根据状态码分支处理，然后轮询监控进度，并通过下载快照获取记录。轮询循环见如何使用异步请求批量抓取数据。

Python

import requests

response = requests.post(
    "https://api.brightdata.com/datasets/v3/scrape",
    params={"dataset_id": "gd_l7q7dkf244hwjntr0", "format": "json"},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"input": [{"url": "https://www.amazon.com/dp/B0FQFB8FMG"}]},
)

if response.status_code == 200:
    print(f"Got {len(response.json())} results")
elif response.status_code == 202:
    print(f"Job running. Snapshot ID: {response.json()['snapshot_id']}")
else:
    response.raise_for_status()

200 返回记录；202 返回快照 ID。其他状态均为错误，见下方的响应部分。各错误的处理方式请参见 Scraper API 错误代码。

自定义输入

您可以在输入结构中添加自定义字段。您在这些字段中发送的内容会随每条记录一起返回到结果中。适用于：

在不同抓取器和数据集之间保持统一的输出结构。
传入 id、row_index 或任意内部键，以便将结果与原始输入行对应起来。

授权

Authorization

string

header

必填

在 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？

查询参数

dataset_id

string

必填

触发数据采集的数据集 ID

custom_output_fields

string

输出列列表，用 | 分隔（例如：url|about.updated_on）。仅包含指定字段的响应。

示例:

"url|about.updated_on"

include_errors

boolean

在结果中包含错误报告

format

enum<string>

默认值:ndjson

响应格式：ndjson（默认，每行一条记录）、json（JSON 数组）或 csv。见输出格式。

可用选项:

ndjson,

json,

csv

请求体

application/json

输入与输出字段过滤 · object
仅输入 · object[]

input

object[]

必填

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

Show child attributes

custom_output_fields

string

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

示例:

"url|about.updated_on"

limit_per_input

integer | null

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

必填范围: x >= 1

示例:

null

响应

成功

记录的 JSON 数组。空数组表示输入未产生记录；请检查输入 URL。

The response is of type string.

示例:

"OK"

基础

数据提取

网页搜索

AI 训练数据

代理

管理 API

工作原理

请求体

超时限制

如何处理 202 响应

自定义输入

授权

查询参数

请求体

响应

​工作原理

​请求体

​超时限制

​如何处理 202 响应

​自定义输入

授权

查询参数

请求体

响应

工作原理

请求体

超时限制

如何处理 202 响应

自定义输入