Fetch API endpoints

This guide shows you how to send each type of Bright Data Fetch API request. It covers a single URL, country targeting, returning only some fields and async batches.

Prerequisites

A Bright Data account with an active API key
Completed the Quickstart

Request structure

Every synchronous request follows the same pattern:

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://..."}]

Each input object takes a required url and an optional country. The Fetch API has one endpoint, so the dataset_id is always gd_m6gjtfmeh43we6cqc.

The /scrape endpoint is built for real-time requests. Bright Data recommends 20 URLs or fewer per request, a best practice rather than a hard limit, and the endpoint waits up to 1 minute. If collection takes longer, the response is HTTP 202 with a snapshot_id instead of data, and collection continues asynchronously. Fetch the result with async requests or have it pushed to you with webhook delivery.

How to fetch a web page by URL

Dataset 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"}]'

You should see a 200 response with one record holding markdown, html2text, page_html, page_title and final_url. Processing time varies with target-site conditions.

Example response

[
  {
    "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"
    }
  }
]

Full response schema

How to fetch a page from a specific country

Add country to an input object to fetch the page from that country. Use a two-letter country code. This request fetches the Google home page from Germany and from the United States:

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"}]'

The first record comes back in German (“Über Google”) and the second in English (“About”), so each page was fetched from the requested country.

Example response

[
  {
    "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"
    }
  }
]

The markdown values are trimmed, and html2text and page_html are left out here.

Send the country code in uppercase, for example US or DE. With a lowercase code such as de the page is still fetched from that country, but the country field in the record comes back null.

How to return only some fields

Set the custom_output_fields query parameter to a pipe-separated list of field names. This request returns only the URL, title and 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"}]'

Example response

[
  {
    "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."
  }
]

Leaving out page_html keeps responses small when you only need text for an LLM.

How to fetch many URLs asynchronously

Send the same body to /trigger instead of /scrape. The Fetch API returns a snapshot_id right away and fetches the pages in the background:

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"}]'

Example response

{"snapshot_id":"sd_mvfklliu2mb3mi6l6y"}

Check progress and download the records with the snapshot_id, as described in async requests.

Quick reference

Request	Endpoint	Key parameter
One or a few URLs	`/datasets/v3/scrape`	`url`
Country targeting	`/datasets/v3/scrape`	`country`, uppercase code
Some fields only	`/datasets/v3/scrape`	`custom_output_fields`
Large batches	`/datasets/v3/trigger`	`url`, returns `snapshot_id`

All four use dataset ID gd_m6gjtfmeh43we6cqc.

Output formats

Control the response format with the format query parameter:

Value	Description
`json`	JSON array
`ndjson`	Newline-delimited JSON, one record per line (default)
`csv`	Comma-separated values

These are the format values for /scrape. The full list, NDJSON (default), JSON, JSON lines, CSV and Parquet, and where each applies is in output formats.

Async batch requests

Fetch hundreds of URLs in a single batch job.

API reference

Full parameter and response field reference.

Get started

Data extraction

Web search

AI training data

Proxy networks

Prerequisites

Request structure

How to fetch a web page by URL

How to fetch a page from a specific country

How to return only some fields

How to fetch many URLs asynchronously

Quick reference

Output formats

Async batch requests

API reference

​Prerequisites

​Request structure

​How to fetch a web page by URL

​How to fetch a page from a specific country

​How to return only some fields

​How to fetch many URLs asynchronously

​Quick reference

​Output formats

​Related

Async batch requests

API reference

Prerequisites

Request structure

How to fetch a web page by URL

How to fetch a page from a specific country

How to return only some fields

How to fetch many URLs asynchronously

Quick reference

Output formats

Related