> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch API endpoints

> Send Bright Data Fetch API requests with copy-paste examples for one URL, country targeting, field selection with custom_output_fields and async batches.

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](https://brightdata.com/?hs_signup=1\&utm_source=docs) with an active API key
* Completed the [Quickstart](/products/scrapers/fetch-api/quickstart)

## Request structure

Every synchronous request follows the same pattern:

```http theme={null}
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`.

<Note>
  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](/products/scrapers/scrapers-library/async-requests) or have it pushed to you with [webhook delivery](/products/scrapers/scrapers-library/data-delivery).
</Note>

## How to fetch a web page by URL

**Dataset ID:** `gd_m6gjtfmeh43we6cqc`

```bash theme={null}
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.

<Accordion title="Example response">
  ```json theme={null}
  [
    {
      "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"
      }
    }
  ]
  ```
</Accordion>

[Full response schema](/api-reference/scrapers/web-content-apis/fetch-api-collect-by-url)

## 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:

```bash theme={null}
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.

<Accordion title="Example response">
  ```json theme={null}
  [
    {
      "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.
</Accordion>

<Note>
  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`.
</Note>

## 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:

```bash theme={null}
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"}]'
```

<Accordion title="Example response">
  ```json theme={null}
  [
    {
      "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."
    }
  ]
  ```
</Accordion>

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:

```bash theme={null}
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"}]'
```

<Accordion title="Example response">
  ```json theme={null}
  {"snapshot_id":"sd_mvfklliu2mb3mi6l6y"}
  ```
</Accordion>

Check progress and download the records with the `snapshot_id`, as described in [async requests](/products/scrapers/scrapers-library/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](/products/scrapers/scrapers-library/data-delivery#which-output-formats-can-i-use).

## Related

<CardGroup cols={2}>
  <Card title="Async batch requests" icon="layer-group" href="/products/scrapers/scrapers-library/async-requests">
    Fetch hundreds of URLs in a single batch job.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/scrapers/web-content-apis/fetch-api-collect-by-url">
    Full parameter and response field reference.
  </Card>
</CardGroup>