fetch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bright Data - Fetch

One URL in, one page out, as markdown, HTML, or a screenshot. Nothing is parsed for you.

Every request is unblocked: IP rotation, browser fingerprints, cookies, CAPTCHA solving and automatic retries, from a country you choose. JavaScript rendering can be forced with the REST body's

render

parameter. The CLI has no flag for it, so a CLI fetch cannot force rendering (a

-f screenshot

is still an image of the rendered page).

输入一个 URL，输出一个页面，可采用 markdown、HTML 或截图格式。不会代你解析任何内容。

每次请求都会解除封锁，包括 IP 轮换、浏览器指纹、Cookie、CAPTCHA 识别以及自动重试，并可选择来源国家。可以通过 REST 请求正文中的

render

参数强制启用 JavaScript 渲染。CLI 没有对应的参数，因此 CLI fetch 无法强制执行渲染（使用

-f screenshot

时，得到的仍是已渲染页面的图像）。

The call

调用方式

CLI. The command is

bdata scrape

, which runs Web Unlocker.

bdata scrape https://example.com/article

Markdown is the default. A first

bdata login

tries to create

cli_unlocker

and, when no default is set, stores it as the zone default, so a fresh login on a normal account needs no

--zone

. It never overwrites a default you already set. A key from agent registration cannot create zones and its account has no

cli_unlocker

, so run

bdata config set default_zone_unlocker agent_unlocker

once. An account set up any other way carries its unlocker zone under another name (

agent_unlocker

from agent registration,

mcp_unlocker

from the MCP server, any name at all when a person made it by hand): find it by the entry whose

"type"

"unblocker"

bdata zones --json

, and pass that name. Override with

--zone <name>

, or

BRIGHTDATA_UNLOCKER_ZONE

, or

bdata config set default_zone_unlocker <name>

bdata

is not recognized, the CLI is not installed or npm's global directory is not on PATH; both fixes live in the

agent-onboarding

skill's Install section.

REST. The same request, for any machine with no CLI.

POST https://api.brightdata.com/request
     Authorization: Bearer $BRIGHTDATA_API_KEY
     Content-Type: application/json

     {"zone":"cli_unlocker","url":"https://example.com/article",
      "format":"raw","data_format":"markdown"}

cli_unlocker

is the name after

bdata login

. On any other account use the name of your

unblocker

zone, as above.

format

is the envelope and

data_format

is the page.

"format":"raw"

returns the body itself,

"format":"json"

wraps it with status and headers.

For code the user keeps, the SDK wraps this same call in one line:

const html = await client.scrapeUrl('https://example.com/article')

. The

brightdata-sdk

skill owns that surface. The

scrape

skill's

references/web-unlocker.md

covers the same one-POST shape and the KYC error codes. The full parameter list, including

render

country

and

method

, is in Bright Data's Web Unlocker API docs.

CLI. 命令为

bdata scrape

，它会运行 Web Unlocker。

bdata scrape https://example.com/article

默认格式为 Markdown。首次执行

bdata login

时会尝试创建

cli_unlocker

；如果尚未设置默认值，就将其保存为 zone 默认值，因此在普通账户上首次登录后无需指定

--zone

。它绝不会覆盖你已设置的默认值。通过 agent 注册获得的 key 无法创建 zone，且其账户中不存在

cli_unlocker

，因此需要执行一次

bdata config set default_zone_unlocker agent_unlocker

。以其他方式设置的账户，其 unlocker zone 会使用其他名称（agent 注册生成的

agent_unlocker

、MCP server 生成的

mcp_unlocker

，或手动创建时的任意名称）：在

bdata zones --json

中查找

"type"

为

"unblocker"

的条目，并传入该名称。可以使用

--zone <name>

、

BRIGHTDATA_UNLOCKER_ZONE

或

bdata config set default_zone_unlocker <name>

覆盖该值。

如果系统无法识别

bdata

，说明 CLI 未安装，或 npm 的全局目录不在 PATH 中；这两种情况的修复方法都位于

agent-onboarding

skill 的 Install 部分。

REST. 相同的请求，适用于任何未安装 CLI 的机器。

POST https://api.brightdata.com/request
     Authorization: Bearer $BRIGHTDATA_API_KEY
     Content-Type: application/json

     {"zone":"cli_unlocker","url":"https://example.com/article",
      "format":"raw","data_format":"markdown"}

cli_unlocker

是执行

bdata login

后的名称。在其他账户上，请按上文所述使用自己的

unblocker

zone 名称。

format

决定外层封装，

data_format

决定页面内容。

"format":"raw"

直接返回正文，

"format":"json"

则在正文中附带状态码和响应头进行封装。

对于用户需要保留的代码，SDK 用一行封装了同一次调用：

const html = await client.scrapeUrl('https://example.com/article')

。

brightdata-sdk

skill 负责这一接口。

scrape

skill 的

references/web-unlocker.md

介绍了相同的单次 POST 请求格式以及 KYC 错误码。包括

render

、

country

和

method

在内的完整参数列表，请参阅 Bright Data 的 Web Unlocker API 文档。

Formats

格式

Want	CLI	REST body	Note
Markdown (default)	`-f markdown`	`"format":"raw","data_format":"markdown"`	For a model, an index, or a human
Raw HTML	`-f html`	`"format":"raw"` , no `data_format`	When the user's own code parses it
Screenshot	`-f screenshot`	`"format":"raw","data_format":"screenshot"`	Binary PNG. The CLI writes `screenshot.png` unless `-o <path>` says otherwise
Response metadata	`-f json`	`"format":"json"`	Status and headers around the body

One honest note on the markdown: links come back exactly as the page wrote them, so a relative link like

/pricing

stays relative and points nowhere once the text leaves the site. That is fine when the output feeds a model, an index or a RAG store. For a standalone document a person will read and click, resolve the links against the page URL first, and say that you did.

The other flags that exist:

--country <code>

--async

-o <path>

--json

--pretty

--timing

, and

--mobile

, which has no effect in the current CLI release.

需求	CLI	REST 请求正文	说明
Markdown（默认）	`-f markdown`	`"format":"raw","data_format":"markdown"`	适用于模型、索引或人类阅读
原始 HTML	`-f html`	`"format":"raw"` ，不设置 `data_format`	当用户自己的代码需要解析它时使用
截图	`-f screenshot`	`"format":"raw","data_format":"screenshot"`	二进制 PNG。除非通过 `-o <path>` 指定其他路径，CLI 会将其写入 `screenshot.png`
响应元数据	`-f json`	`"format":"json"`	在正文外附加状态码和响应头

关于 markdown 有一点需要如实说明：链接会完全按页面原始写法返回，因此像

/pricing

这样的相对链接仍保持相对形式，文本离开站点后将无法指向任何位置。当输出用于馈送模型、索引或 RAG 存储时，这样没有问题。如果输出是供人阅读并点击的独立文档，应先根据页面 URL 将这些链接解析为绝对地址，并说明你已执行此操作。

其他可用的参数包括：

--country <code>

、

--async

、

-o <path>

、

--json

、

--pretty

、

--timing

和

--mobile

，其中

--mobile

在当前的 CLI 版本中不起作用。

Example - one blocked article

示例 - 抓取一篇被阻止的文章

The ask: "my script gets a 403 on this URL, I just need the article text"

One URL, and the page itself is the answer. Stay in this skill.
The 403 is the reason to be here, not a problem to route around. Unblocking is the product.
Text for a human or a model, so markdown, which is already the default.

bdata scrape https://www.example-news.com/2026/08/some-article

Then state the choice in one line the user can override with one word:

Fetched the page with Web Unlocker as markdown. Say
fields
if you want the data fields pulled out instead, and I will use a maintained scraper.

需求：“我的脚本访问这个 URL 时收到 403，我只需要文章文本”

只有一个 URL，而且页面本身就是答案。请继续使用本 skill。
出现 403 正是使用此功能的原因，而不是需要另行绕开的问题。解除封锁正是本产品的核心能力。
需要获取供人或模型阅读的文本，因此选择 markdown，它已经是默认格式。

bdata scrape https://www.example-news.com/2026/08/some-article

然后用一句话说明选择，用户只需说出一个词即可更改：

已使用 Web Unlocker 以 markdown 格式获取页面。如果你想改为提取数据字段，请说
fields
，届时我会使用维护中的 scraper。

When a fetch is refused

fetch 被拒绝时

Read the error first. A 403 from the target site is not on this list, because that is the ordinary case this skill exists to solve.

The message contains	What it means
`No Web Unlocker zone specified.`	No zone resolved. Take the name of the `"type":"unblocker"` entry in `bdata zones --json` and pass it as `--zone` , or save it once with `bdata config set default_zone_unlocker <name>` . Do not log in again: it replaces the stored key.
`zone "<name>" not found`	The resolved zone does not exist on this account, often `cli_unlocker` on an account made by agent registration. Take the `"type":"unblocker"` entry from `bdata zones --json` and save it with `bdata config set default_zone_unlocker <name>` .

Two other refusals are not this skill's to fix. A missing or dead key (

No API key found

, or 401) means the machine is not logged in. A few targets need KYC on the account before Bright Data will serve them: sites that block themselves in robots.txt such as Reddit, government sites, sites on Bright Data's blocked list, and targets its compliance policy does not permit. Most sites need none of this. Both belong to the

agent-onboarding

skill, which carries the exact error codes. Send the user there, and never send anyone to KYC before a call has actually been refused.

先查看错误信息。目标站点返回的 403 不属于下表所列的拒绝情况，因为这正是本 skill 要解决的常见场景。

错误消息包含	含义
`No Web Unlocker zone specified.`	未解析出 zone。从 `bdata zones --json` 中取出 `"type":"unblocker"` 条目的名称，并将其作为 `--zone` 传入；也可以使用 `bdata config set default_zone_unlocker <name>` 保存一次。不要再次登录，因为这会替换已存储的 key。
`zone "<name>" not found`	解析出的 zone 在当前账户中不存在；这常见于由 agent 注册创建的账户仍使用 `cli_unlocker` 。从 `bdata zones --json` 中取出 `"type":"unblocker"` 条目的名称，并使用 `bdata config set default_zone_unlocker <name>` 保存。

另外两种拒绝情况不由本 skill 处理。key 缺失或失效（

No API key found

或 401）表示机器尚未登录。某些目标站点需要先在账户上完成 KYC，Bright Data 才会提供抓取服务，例如在 robots.txt 中屏蔽自身的站点（如 Reddit）、政府网站、Bright Data 封禁列表中的站点，以及其合规政策不允许的目标站点。大多数站点都不需要上述处理。这两类问题均应交由

agent-onboarding

skill 处理，该 skill 包含具体的错误码。应将用户引导至该 skill；在调用真正被拒绝之前，绝不要引导用户去完成 KYC。

Handoff boundaries

任务转交边界

The ask	Skill
Data fields, or many pages of one site	`scrape`
The same site fetched twice with a parser in between	`scrape` , because that is a scraper being written by hand
A query with no URL	`search`
Their own browser code, pointed at an unblocked browser	`browser`

A fetch whose real purpose is pulling data fields out of the page is a scrape ask. Hand it over.

Never promise JavaScript rendering on a CLI markdown or HTML fetch; when a page needs it, use the REST call with

"render":"true"

. Never reach for a browser or a proxy because a page returned 403. That is what this one call already handles.

需求	Skill
提取数据字段，或抓取同一站点的多个页面	`scrape`
对同一站点执行两次 fetch，中间使用解析器	`scrape` ，因为这实际上是在手动编写 scraper
不含 URL 的查询	`search`
用户自己的浏览器代码，指向一个已解除封锁的浏览器	`browser`

如果执行 fetch 的真正目的是从页面中提取数据字段，那么这属于 scrape 请求，应转交相应 skill。

绝不要承诺 CLI 的 markdown 或 HTML fetch 能够执行 JavaScript 渲染；页面需要渲染时，使用带有

"render":"true"

的 REST 调用。不要因为页面返回 403 就转而使用 browser 或 proxy，因为这一次调用已经能够处理这种情况。