Scraper async requests

curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":[{"user_name":"zoobarcelona"}],"limit_per_input":null}' \
  "https://api.brightdata.com/datasets/v3/trigger?dataset_id=gd_l1vikfch901nx3by4&notify=false&include_errors=true&type=discover_new&discover_by=user_name"

import requests

response = requests.post(
    "https://api.brightdata.com/datasets/v3/trigger",
    params={
        "dataset_id": "gd_l1vikfch901nx3by4",
        "notify": "false",
        "include_errors": "true",
        "type": "discover_new",
        "discover_by": "user_name",
    },
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"input": [{"user_name": "zoobarcelona"}], "limit_per_input": None},
)

snapshot = response.json()
print("Snapshot ID:", snapshot["snapshot_id"])

import axios from "axios";

const response = await axios.post(
  "https://api.brightdata.com/datasets/v3/trigger",
  { input: [{ user_name: "zoobarcelona" }], limit_per_input: null },
  {
    params: {
      dataset_id: "gd_l1vikfch901nx3by4",
      notify: false,
      include_errors: true,
      type: "discover_new",
      discover_by: "user_name",
    },
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  }
);

console.log("Snapshot ID:", response.data.snapshot_id);

const params = new URLSearchParams({
  dataset_id: "gd_l1vikfch901nx3by4",
  notify: "false",
  include_errors: "true",
  type: "discover_new",
  discover_by: "user_name",
});

const response = await fetch(`https://api.brightdata.com/datasets/v3/trigger?${params}`, {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ input: [{ user_name: "zoobarcelona" }], limit_per_input: null }),
});

const snapshot = await response.json();
console.log("Snapshot ID:", snapshot.snapshot_id);

{
  "snapshot_id": "sd_m4x7enmven8djfqak"
}

{
  "error": "Invalid input provided",
  "code": "validation_error",
  "type": "validation",
  "line": "{\"url\":\"not-a-url\",\"asin\":\"\",\"zipcode\":\"\",\"language\":\"\"}",
  "index": 1,
  "errors": [
    [
      "url",
      "This field must be a valid url"
    ]
  ]
}

Invalid credentials

dataset does not exist

POST

datasets

trigger

curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":[{"user_name":"zoobarcelona"}],"limit_per_input":null}' \
  "https://api.brightdata.com/datasets/v3/trigger?dataset_id=gd_l1vikfch901nx3by4&notify=false&include_errors=true&type=discover_new&discover_by=user_name"

import requests

response = requests.post(
    "https://api.brightdata.com/datasets/v3/trigger",
    params={
        "dataset_id": "gd_l1vikfch901nx3by4",
        "notify": "false",
        "include_errors": "true",
        "type": "discover_new",
        "discover_by": "user_name",
    },
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"input": [{"user_name": "zoobarcelona"}], "limit_per_input": None},
)

snapshot = response.json()
print("Snapshot ID:", snapshot["snapshot_id"])

import axios from "axios";

const response = await axios.post(
  "https://api.brightdata.com/datasets/v3/trigger",
  { input: [{ user_name: "zoobarcelona" }], limit_per_input: null },
  {
    params: {
      dataset_id: "gd_l1vikfch901nx3by4",
      notify: false,
      include_errors: true,
      type: "discover_new",
      discover_by: "user_name",
    },
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  }
);

console.log("Snapshot ID:", response.data.snapshot_id);

const params = new URLSearchParams({
  dataset_id: "gd_l1vikfch901nx3by4",
  notify: "false",
  include_errors: "true",
  type: "discover_new",
  discover_by: "user_name",
});

const response = await fetch(`https://api.brightdata.com/datasets/v3/trigger?${params}`, {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ input: [{ user_name: "zoobarcelona" }], limit_per_input: null }),
});

const snapshot = await response.json();
console.log("Snapshot ID:", snapshot.snapshot_id);

{
  "snapshot_id": "sd_m4x7enmven8djfqak"
}

{
  "error": "Invalid input provided",
  "code": "validation_error",
  "type": "validation",
  "line": "{\"url\":\"not-a-url\",\"asin\":\"\",\"zipcode\":\"\",\"language\":\"\"}",
  "index": 1,
  "errors": [
    [
      "url",
      "This field must be a valid url"
    ]
  ]
}

Invalid credentials

dataset does not exist

curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":[{"user_name":"zoobarcelona"}],"limit_per_input":null}' \
  "https://api.brightdata.com/datasets/v3/trigger?dataset_id=gd_l1vikfch901nx3by4&notify=false&include_errors=true&type=discover_new&discover_by=user_name"

import requests

response = requests.post(
    "https://api.brightdata.com/datasets/v3/trigger",
    params={
        "dataset_id": "gd_l1vikfch901nx3by4",
        "notify": "false",
        "include_errors": "true",
        "type": "discover_new",
        "discover_by": "user_name",
    },
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"input": [{"user_name": "zoobarcelona"}], "limit_per_input": None},
)

snapshot = response.json()
print("Snapshot ID:", snapshot["snapshot_id"])

import axios from "axios";

const response = await axios.post(
  "https://api.brightdata.com/datasets/v3/trigger",
  { input: [{ user_name: "zoobarcelona" }], limit_per_input: null },
  {
    params: {
      dataset_id: "gd_l1vikfch901nx3by4",
      notify: false,
      include_errors: true,
      type: "discover_new",
      discover_by: "user_name",
    },
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  }
);

console.log("Snapshot ID:", response.data.snapshot_id);

const params = new URLSearchParams({
  dataset_id: "gd_l1vikfch901nx3by4",
  notify: "false",
  include_errors: "true",
  type: "discover_new",
  discover_by: "user_name",
});

const response = await fetch(`https://api.brightdata.com/datasets/v3/trigger?${params}`, {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ input: [{ user_name: "zoobarcelona" }], limit_per_input: null }),
});

const snapshot = await response.json();
console.log("Snapshot ID:", snapshot.snapshot_id);

POST /datasets/v3/trigger starts an asynchronous Scraper API collection and returns a snapshot_id. The example discovers Instagram profiles by username (gd_l1vikfch901nx3by4). To get the records in the same response instead, call POST /datasets/v3/scrape with the same query and body.

Request body

Send an object with an input array:

Field	Type	Description
`input`	array of objects, required	The inputs to scrape. The fields depend on the scraper, for example `url` or `user_name`
`limit_per_input`	integer or `null`	Maximum records returned per input, or `null`
`deliver`	object	Delivery destination for this job. See How to deliver Scraper API results

A bare JSON array of input objects is also accepted. It cannot carry limit_per_input or deliver.

Query parameters in the example

Parameter	Value in the example	Description
`dataset_id`	`gd_l1vikfch901nx3by4`	The scraper to run
`notify`	`false`	Whether to send a completion notification
`include_errors`	`true`	Include error records in the results
`type`	`discover_new`	Discovery scrapers only
`discover_by`	`user_name`	Discovery scrapers only. The discovery method, which differs per scraper

The example sends no format parameter.

Output formats

Scraper API output formats are NDJSON (default), JSON, JSON lines, CSV and Parquet. Each one has its own API value, and not every value is accepted everywhere:

Format	API value	`format` on `/scrape`	`format` on `/trigger`	`deliver.filename.extension`
NDJSON (default)	`ndjson`	Yes	Yes	Yes
JSON	`json`	Yes	Yes	Yes
JSON lines	`jsonl`	Yes	Yes	Yes
CSV	`csv`	Yes	Yes	Yes
Parquet	`parquet`	Not listed	Not listed	Yes

A /scrape request or a snapshot download with no format returns NDJSON, one record per line. Set format=json to get a JSON array instead. Verified on September 30, 2026. “Not listed” means the value is not in the API specification for that parameter. NDJSON and JSON lines are separate API values, ndjson and jsonl. Related guide: How to scrape in bulk with async requests Error messages and fixes: Scraper API error codes

Authorizations

Authorization

string

header

required

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

How to authenticate:

Obtain your API Key from the Bright Data account settings at https://brightdata.com/cp/setting/users
Include the API Key in the Authorization header of your requests
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. Read more about Dataset ID.

Example:

"gd_l1vikfnt1wgvvqz95w"

custom_output_fields

string

The "custom_output_fields" parameter is used to filter the response data to include only the specified fields. You can list the output columns you want, separated by a pipe (|).

For example, if you want the response to include only the URL and the date it was last updated, you would set the parameter to "url|about.updated_on". This allows you to customize the data output to include only the fields relevant to your needs.

Example:

"url|about.updated_on"

type

enum<string>

Set it to "discover_new" to trigger a collection that includes a discovery phase.

Enables a discovery phase that finds new entities or products using methods like search, categories, or keywords. Use this when collecting data where specific targets aren't known in advance. It will discover new information based on your provided inputs rather than working with predefined data points.

Available options:

discover_new

discover_by

string

Specifies the method used for discovering new data during a collection. Here are some available options:

keyword: Uses keywords to discover new entities or products. Example: "smartphones" - This will trigger a collection to discover new smartphone products or entities.
best_sellers_url: Uses a URL that lists best-selling items to discover new products. Example: "https://example.com/best-sellers" - This URL will be used to discover products listed as best sellers on the site.
category_url: Uses a URL that lists categories to discover new entities within those categories. Example: "https://example.com/electronics" - This URL will be used to discover new products within the electronics category.
location: Uses a location-based approach to discover entities relevant to that location. Example: "New York" - This will trigger a collection to discover data related to the specified location.

include_errors

boolean

Include errors report with the results. By setting "include_errors" to true, you will receive a detailed report of any errors that occur during the data collection.

Example:

true

limit_per_input

number

Limit the number of results per input. Sending limit_per_input in the request body, next to input, is recommended. The query parameter also caps results on /scrape and /trigger (verified September 30, 2026).

Required range: x >= 1

limit_multiple_results

number

Limit the total number of results

Required range: x >= 1

notify

boolean

Specify whether notifications should be sent upon completion of the data collection job. When set to true, it enables notifications to be sent to the specified webhook, informing you about the status or completion of the collection.

Example:

true

endpoint

string

Specify the Webhook URL that should be called for the data collection process.

Example:

"https://example.com/webhook"

format

enum<string>

Format of the delivered data: json, ndjson, jsonl or csv. To download the snapshot instead, set format on the download request; without it the download is NDJSON. For a Parquet file, deliver to storage with deliver.filename.extension set to parquet. See output formats.

Available options:

json,

ndjson,

jsonl,

csv

Example:

"json"

auth_header

string

Authorization header for webhook delivery

uncompressed_webhook

boolean

By default, the data will be sent compressed. Pass true to send it uncompressed

Example:

true

Body

Send an object with an input array. A bare array of input objects is also accepted. You can also upload the inputs as a CSV file.

Object with input · object
Bare array (also accepted) · object[]

An input array plus optional fields such as limit_per_input.

input

object[]

required

Array of input objects. The fields depend on the scraper, for example url or user_name.

Show child attributes

Example:

[
  {
    "url": "https://www.airbnb.com/rooms/50122531"
  },
  {
    "url": "https://www.airbnb.com/rooms/50127677"
  }
]

limit_per_input

integer | null

Maximum number of records to return per input, or null. Applies to discovery requests, whose result count is otherwise open-ended.

Required range: x >= 1

Example:

null

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

Collection job successfully started

snapshot_id

string

A Snapshot ID is a unique identifier for a specific data snapshot, used to retrieve results from a data collection job triggered via the API. Read more about Snapshot ID.

Example:

"sd_m4x7enmven8djfqak"

Essentials

Data extraction

Web search

AI training data

Proxy

Administrative APIs

Request body

Query parameters in the example

Output formats

Authorizations

Query Parameters

Body

Response

​Request body

​Query parameters in the example

​Output formats

Authorizations

Query Parameters

Body

Response

Request body

Query parameters in the example

Output formats