/fetch

name: fetch
description: 'Use when the user wants one known URL returned as content: "get me this page", read this article, this page as markdown, save the raw HTML, screenshot this page, or page text for a RAG index or model context. Also when a plain fetch of a URL came back blocked or challenged instead of the real page: a 403 or another error status, a CAPTCHA, a bot wall, or an empty body. Wraps Bright Data Web Unlocker, so a blocked page still comes back. Not records or many pages of data from a site (use scrape), not a search query with no URL (use search), not driving a browser with your own Playwright, Puppeteer or Selenium code (use browser), not cost or credits (use billing), not auth or KYC failures (use agent-onboarding).'

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).

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"` is `"unblocker"` in `bdata zones --json`, and pass that name. Override with `--zone <name>`, or `BRIGHTDATA_UNLOCKER_ZONE`, or `bdata config set default_zone_unlocker <name>`.

If `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.

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.

Example - one blocked article

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

1. One URL, and the page itself is the answer. Stay in this skill. 2. The 403 is the reason to be here, not a problem to route around. Unblocking is the product. 3. 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.

When a fetch is refused

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