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

# Scraper async requests

> Trigger a Bright Data Scraper API async collection with POST /datasets/v3/trigger. Returns a snapshot ID to monitor progress and download results.

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

  ```python Python (requests) theme={null}
  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"])
  ```

  ```javascript Node.js (Axios) theme={null}
  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);
  ```

  ```javascript Node.js (fetch) theme={null}
  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);
  ```
</RequestExample>

`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`](/api-reference/scrapers/synchronous-requests) 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](/products/scrapers/scrapers-library/data-delivery) |

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](/products/scrapers/scrapers-library/async-requests)

Error messages and fixes: [Scraper API error codes](/products/scrapers/error-codes)


## OpenAPI

````yaml api-reference/rest-api/scraper/scraper-rest-api.json POST /datasets/v3/trigger
openapi: 3.1.0
info:
  title: Bright Data Scrapers
  description: >-
    API for automated web data collection and extraction with support for
    various scraping scenarios and delivery options
  version: 1.0.0
servers:
  - url: https://api.brightdata.com
security:
  - bearerAuth: []
paths:
  /datasets/v3/trigger:
    post:
      description: Trigger a web scraping collection based on provided inputs
      parameters:
        - name: dataset_id
          description: >-
            Dataset ID for which data collection is triggered. Read more about
            [Dataset ID](/api-reference/terminology#dataset-id).
          in: query
          required: true
          schema:
            type: string
            example: gd_l1vikfnt1wgvvqz95w
        - name: custom_output_fields
          description: >-
            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.
          in: query
          required: false
          schema:
            type: string
            example: url|about.updated_on
        - name: type
          in: query
          schema:
            type: string
            enum:
              - discover_new
          description: >-
            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.
        - name: discover_by
          in: query
          schema:
            type: string
          description: >-
            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.
        - name: include_errors
          in: query
          schema:
            type: boolean
            example: true
          description: >-
            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.
        - name: limit_per_input
          in: query
          schema:
            type: number
            minimum: 1
          description: >-
            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).
        - name: limit_multiple_results
          in: query
          schema:
            type: number
            minimum: 1
          description: Limit the total number of results
        - name: notify
          in: query
          schema:
            type: boolean
            example: true
          description: >-
            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.
        - name: endpoint
          in: query
          schema:
            type: string
            example: https://example.com/webhook
          description: >-
            Specify the Webhook URL that should be called for the data
            collection process.
        - name: format
          in: query
          schema:
            type: string
            enum:
              - json
              - ndjson
              - jsonl
              - csv
            example: json
          description: >-
            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](/products/scrapers/scrapers-library/data-delivery#which-output-formats-can-i-use).
        - name: auth_header
          in: query
          schema:
            type: string
          description: Authorization header for webhook delivery
        - name: uncompressed_webhook
          in: query
          schema:
            type: boolean
            example: true
          description: >-
            By default, the data will be sent compressed. Pass true to send it
            uncompressed
      requestBody:
        required: true
        description: >-
          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.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerInput'
            example:
              input:
                - user_name: zoobarcelona
              limit_per_input: null
          multipart/form-data:
            schema:
              type: object
              properties:
                data:
                  type: string
                  format: binary
                  description: >-
                    A CSV file containing the URLs or other inputs required by
                    the scraper
      responses:
        '200':
          description: Collection job successfully started
          content:
            application/json:
              schema:
                type: object
                properties:
                  snapshot_id:
                    type: string
                    description: >-
                      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](/api-reference/terminology#snapshot-id).
                    example: sd_m4x7enmven8djfqak
              example:
                snapshot_id: sd_m4x7enmven8djfqak
        '400':
          description: >-
            Bad request - invalid input parameters


            Messages:

            - `{"error": "Invalid input provided", "code": "validation_error",
            "errors": [[FIELD, REASON]]}`: An input field failed validation;
            `errors` names the field and the reason, for example `["url", "This
            field must be a valid url"]`. Fix the input value and resend

            - `{"error": "Parser cannot parse input: ...", "code":
            "parse_error"}`: The request body is not valid JSON. Fix the JSON
            and resend

            - Invalid attachments

            - This dataset is not allowed for API

            - This dataset is not ready yet

            - No data to trigger

            - Should be at least `LIMIT` inputs
          content:
            application/json:
              schema:
                type: object
                description: Error body
              example:
                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
        '401':
          description: >-
            Messages (plain text):

            - `Credentials are missing`: No `Authorization` header was sent

            - `Auth method is not supported`: The `Authorization` header is not
            in a supported format

            - `Invalid credentials`: The API key is wrong


            Send `Authorization: Bearer YOUR_API_KEY` with a valid API key
          content:
            text/plain:
              schema:
                type: string
              example: Invalid credentials
        '404':
          description: >-
            Messages (plain text):

            - `Collector not found`: The request has no `dataset_id` query
            parameter

            - `dataset does not exist`: No scraper matches the `dataset_id`
          content:
            text/plain:
              schema:
                type: string
              example: dataset does not exist
        '429':
          description: >-
            Messages:

            - You have too many running jobs for this dataset. Please wait until
            some of them finish or consider combining multiple inputs into a
            single request. Running jobs: `RUNNING_JOBS>=JOBS_LIMIT`


            A 429 means you exceeded the concurrent job limit, and 25 or more
            429s within 5 minutes blacklists the IP. The recovery steps, the
            backoff rule and a code example are in [Getting a 429 Too Many
            Requests
            error?](/products/scrapers/scrapers-library/async-requests#getting-a-429-too-many-requests-error)
            on the async guide.
        '500':
          description: |-
            Messages:
            - Internal server error
components:
  schemas:
    TriggerInput:
      oneOf:
        - $ref: '#/components/schemas/TriggerRequest'
          title: Object with input
        - $ref: '#/components/schemas/TriggerInputArray'
          title: Bare array (also accepted)
      example:
        input:
          - user_name: zoobarcelona
        limit_per_input: null
    TriggerRequest:
      type: object
      description: An `input` array plus optional fields such as `limit_per_input`.
      required:
        - input
      properties:
        input:
          $ref: '#/components/schemas/TriggerInputArray'
          description: >-
            Array of input objects. The fields depend on the scraper, for
            example `url` or `user_name`.
        limit_per_input:
          type:
            - integer
            - 'null'
          minimum: 1
          description: >-
            Maximum number of records to return per input, or `null`. Applies to
            discovery requests, whose result count is otherwise open-ended.
          example: null
        custom_output_fields:
          type: string
          description: >-
            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
      example:
        input:
          - user_name: zoobarcelona
        limit_per_input: null
    TriggerInputArray:
      type: array
      description: >-
        A bare JSON array of input objects. Also accepted; it cannot carry
        `limit_per_input`.
      example:
        - url: https://www.airbnb.com/rooms/50122531
        - url: https://www.airbnb.com/rooms/50127677
      items:
        type: object
        additionalProperties:
          description: >-
            Properties vary based on the dataset requirements. Most commonly
            includes 'url' field. 
             Example: ```[{"url":"https://www.airbnb.com/rooms/50122531"},{"url":"https://www.airbnb.com/rooms/50127677"}]```
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        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
      bearerFormat: API Key

````