Fetch API 端点

本指南展示如何发送各类 Bright Data Fetch API 请求，包括单个 URL、国家定位、只返回部分字段以及异步批量请求。

前置条件

一个拥有有效 API 密钥的 Bright Data 账户
已完成快速开始

请求结构

每个同步请求都遵循相同的模式：

POST https://api.brightdata.com/datasets/v3/scrape?dataset_id=gd_m6gjtfmeh43we6cqc&format=json
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

[{"url": "https://..."}]

每个输入对象包含必填的 url 和可选的 country。Fetch API 只有一个端点，因此 dataset_id 始终为 gd_m6gjtfmeh43we6cqc。

/scrape 端点专为实时请求设计。Bright Data 建议每个请求不超过 20 个 URL，这是最佳实践，而非硬性限制，该端点最多等待 1 分钟。如果采集时间更长，响应将是 HTTP 202 和 snapshot_id，而不是数据，采集会以异步方式继续。可通过异步请求获取结果，或通过 webhook 交付推送给您。

如何按 URL 获取网页

数据集 ID： gd_m6gjtfmeh43we6cqc

curl -X POST \
  "https://api.brightdata.com/datasets/v3/scrape?dataset_id=gd_m6gjtfmeh43we6cqc&format=json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"url": "https://example.com"}]'

您应该会看到 200 响应，其中一条记录包含 markdown、html2text、page_html、page_title 和 final_url。处理时间取决于目标网站的情况。

示例响应

[
  {
    "markdown": "This domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for testing and monitoring purposes.",
    "url": "https://example.com/",
    "final_url": "https://example.com/",
    "html2text": "This domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for\ntesting and monitoring purposes.",
    "page_html": "<!doctype html><html lang=en><head><meta charset=utf-8>...<title>Example Domain</title>...</head><body><p>This domain is for use in documentation examples without needing permission. ...</p></body></html>\n",
    "page_title": "Example Domain",
    "country": null,
    "timestamp": "2026-10-19T18:10:21.213Z",
    "input": {
      "url": "https://example.com"
    }
  }
]

完整响应结构

如何从指定国家获取网页

在输入对象中添加 country，即可从该国家获取网页。请使用两位国家代码。以下请求分别从德国和美国获取 Google 首页：

curl -X POST \
  "https://api.brightdata.com/datasets/v3/scrape?dataset_id=gd_m6gjtfmeh43we6cqc&format=json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"url": "https://www.google.com/", "country": "de"}, {"url": "https://www.google.com/", "country": "US"}]'

第一条记录为德语（“Über Google”），第二条为英语（“About”），说明每个网页都是从请求的国家获取的。

示例响应

[
  {
    "markdown": "[Über Google](https://about.google/?fg=1&utm%5Fsource=google-DE&utm%5Fmedium=referral&utm%5Fcampaign=hp-header)[Store](https://store.google.com/DE?utm%5Fsource=...",
    "url": "https://www.google.com/",
    "final_url": "https://www.google.com/",
    "page_title": "Google",
    "country": null,
    "timestamp": "2026-10-19T18:10:23.654Z",
    "input": {
      "url": "https://www.google.com/",
      "country": "de"
    }
  },
  {
    "markdown": "[About](https://about.google/?fg=1&utm%5Fsource=google-US&utm%5Fmedium=referral&utm%5Fcampaign=hp-header)[Store](https://store.google.com/US?utm%5Fsource=...",
    "url": "https://www.google.com/",
    "final_url": "https://www.google.com/",
    "page_title": "Google",
    "country": "US",
    "timestamp": "2026-10-19T18:10:50.519Z",
    "input": {
      "url": "https://www.google.com/",
      "country": "US"
    }
  }
]

此处的 markdown 值已截断，并省略了 html2text 和 page_html。

请使用大写国家代码，例如 US 或 DE。使用 de 等小写代码时，仍会从该国家获取网页，但记录中的 country 字段会返回 null。

如何只返回部分字段

将 custom_output_fields 查询参数设置为以竖线分隔的字段名列表。以下请求只返回 URL、标题和 Markdown：

curl -X POST \
  "https://api.brightdata.com/datasets/v3/scrape?dataset_id=gd_m6gjtfmeh43we6cqc&format=json&custom_output_fields=url|page_title|markdown" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"url": "https://example.com"}]'

示例响应

[
  {
    "url": "https://example.com/",
    "page_title": "Example Domain",
    "markdown": "This domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for testing and monitoring purposes."
  }
]

不返回 page_html 可以在只需要为 LLM 提供文本时减小响应体积。

如何异步获取大量 URL

将相同的请求体发送到 /trigger 而不是 /scrape。Fetch API 会立即返回 snapshot_id，并在后台获取网页：

curl -X POST \
  "https://api.brightdata.com/datasets/v3/trigger?dataset_id=gd_m6gjtfmeh43we6cqc&format=json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"url": "https://example.com"}, {"url": "https://en.wikipedia.org/wiki/Web_scraping"}]'

示例响应

{"snapshot_id":"sd_mvfklliu2mb3mi6l6y"}

使用 snapshot_id 查看进度并下载记录，具体方法见异步请求。

快速参考

请求	端点	关键参数
一个或少量 URL	`/datasets/v3/scrape`	`url`
国家定位	`/datasets/v3/scrape`	`country`，大写代码
只返回部分字段	`/datasets/v3/scrape`	`custom_output_fields`
大批量	`/datasets/v3/trigger`	`url`，返回 `snapshot_id`

四种请求都使用数据集 ID gd_m6gjtfmeh43we6cqc。

输出格式

通过 format 查询参数控制响应格式：

值	说明
`json`	JSON 数组
`ndjson`	换行分隔的 JSON，每行一条记录（默认）
`csv`	逗号分隔值

以上是 /scrape 支持的 format 值。完整列表，即 NDJSON（默认）、JSON、JSON lines、CSV 和 Parquet，以及各自的适用场景，请参阅输出格式。

异步批量请求

在单个批处理作业中获取数百个 URL。

API 参考

完整的参数和响应字段参考。

开始使用

数据提取

网页搜索

AI 训练数据

代理网络

前置条件

请求结构

如何按 URL 获取网页

如何从指定国家获取网页

如何只返回部分字段

如何异步获取大量 URL

快速参考

输出格式

相关内容

异步批量请求

API 参考

​前置条件

​请求结构

​如何按 URL 获取网页

​如何从指定国家获取网页

​如何只返回部分字段

​如何异步获取大量 URL

​快速参考

​输出格式

​相关内容

异步批量请求

API 参考

前置条件

请求结构

如何按 URL 获取网页

如何从指定国家获取网页

如何只返回部分字段

如何异步获取大量 URL

快速参考

输出格式

相关内容