Skip to main content
POST
/
datasets
/
v3
/
scrape
Scrape data and return it directly in the response.
curl --request POST \
  --url https://api.brightdata.com/datasets/v3/scrape \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "custom_input_fields": [
    "url",
    "prompt",
    "index_custom"
  ],
  "input": [
    {
      "url": "https://chatgpt.com/",
      "prompt": "Top hotels in New York",
      "index_custom": "abd45424"
    }
  ]
}
'
"OK"

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.

​
Custom inputs

You can add custom fields to your input schema, and whatever you send in those fields will be returned in the results for each record/job. This is useful for:
  • Unified schema: Keep the same output structure across different scrapers/datasets.
  • Index / reference fields: Pass an id, row_index, or any internal key so you can easily match results back to the original input rows.

Authorizations

​
Authorization
string
header
required

Use your Bright Data API Key as a Bearer token in the Authorization header.

How to authenticate:

  1. Obtain your API Key from the Bright Data account settings at https://brightdata.com/cp/setting/users
  2. Include the API Key in the Authorization header of your requests
  3. Format: Authorization: Bearer YOUR_API_KEY

Example:

Authorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df

Learn how to get your Bright Data API key: https://docs.brightdata.com/api-reference/authentication

Query Parameters

​
dataset_id
string
required

Dataset ID for which data collection is triggered.

​
custom_output_fields
string

List of output columns, separated by | (e.g., url|about.updated_on). Filters the response to include only the specified fields.

Example:

"url|about.updated_on"

​
include_errors
boolean

Include errors report with the results.

​
format
enum<string>
default:json

Specifies the format of the response (default: ndjson).

Available options:
ndjson,
json,
csv

Body

application/json
​
input
object[]
required

List of input items to scrape.

Example:
[
  {
    "url": "https://chatgpt.com/",
    "prompt": "Top hotels in New York",
    "index_custom": "abd45424"
  }
]
​
custom_input_fields
string[]

List of custom input field names whose values are passed through and returned unchanged in the results for each record.

The name of a custom input field to be accepted and returned in the results.

Example:
["url", "prompt", "index_custom"]
​
custom_output_fields
string

List of output columns, separated by | (e.g., url|about.updated_on). Filters the response to include only the specified fields.

Example:

"url|about.updated_on"

Response

OK

The response is of type string.

Example:

"OK"