Bright Data Datasets API

openapi: 3.0.3
info:
  title: Bright Data Platform API
  description: >-
    OpenAPI description of Bright Data's REST platform APIs served from
    https://api.brightdata.com - the Web Scraper API (dataset trigger,
    progress, snapshot), the synchronous scrape endpoint, the SERP API and Web
    Unlocker (both POST /request with a zone), account/zone management, and a
    Browser API session-metadata endpoint. Paths and methods are grounded in
    Bright Data's published API reference; request/response schemas are
    representative and modeled, not exhaustively reconciled. The Scraping
    Browser's Chrome DevTools Protocol WebSocket surface is described
    separately in asyncapi/brightdata-asyncapi.yml.
  termsOfService: https://brightdata.com/legal/tos
  contact:
    name: Bright Data Support
    url: https://brightdata.com/contact
  version: '3.0'
servers:
  - url: https://api.brightdata.com
    description: Bright Data platform API base host.
security:
  - bearerAuth: []
tags:
  - name: Web Scraper
    description: Trigger dataset collections and retrieve snapshots.
  - name: SERP
    description: Search-engine results via zone-based requests.
  - name: Web Unlocker
    description: Single-page unlocking via zone-based requests.
  - name: Zones
    description: Account and proxy zone management.
  - name: Browser API
    description: Scraping Browser session metadata (CDP itself is over WebSocket).
paths:
  /datasets/v3/trigger:
    post:
      operationId: triggerCollection
      tags:
        - Web Scraper
      summary: Trigger an asynchronous Web Scraper collection.
      description: >-
        Starts an asynchronous collection for a pre-built scraper (dataset).
        Returns a snapshot_id used to poll progress and download results.
      parameters:
        - name: dataset_id
          in: query
          required: true
          description: Scraper / dataset identifier (e.g. gd_l1viktl72bvl7bjuj0).
          schema:
            type: string
        - name: format
          in: query
          required: false
          description: Output format.
          schema:
            type: string
            enum: [json, ndjson, jsonl, csv]
        - name: include_errors
          in: query
          required: false
          schema:
            type: boolean
        - name: custom_output_fields
          in: query
          required: false
          description: Pipe- or comma-delimited list of fields to return.
          schema:
            type: string
        - name: notify
          in: query
          required: false
          description: Webhook URL notified when the snapshot is ready.
          schema:
            type: string
            format: uri
      requestBody:
        required: true
        description: Array of input objects for the scraper (commonly a url per item).
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScraperInput'
            example:
              - url: https://www.airbnb.com/rooms/50122531
              - url: https://www.airbnb.com/rooms/50127677
      responses:
        '200':
          description: Collection triggered; snapshot identifier returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /datasets/v3/scrape:
    post:
      operationId: scrapeSynchronous
      tags:
        - Web Scraper
      summary: Synchronous Web Scraper collection.
      description: >-
        Runs a scraper synchronously and returns records in the response body
        (best for small, latency-sensitive jobs).
      parameters:
        - name: dataset_id
          in: query
          required: true
          schema:
            type: string
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [json, ndjson, jsonl, csv]
        - name: include_errors
          in: query
          required: false
          schema:
            type: boolean
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScraperInput'
      responses:
        '200':
          description: Scraped records.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /datasets/v3/progress/{snapshot_id}:
    get:
      operationId: getSnapshotProgress
      tags:
        - Web Scraper
      summary: Monitor snapshot collection progress.
      parameters:
        - name: snapshot_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Snapshot progress status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProgressResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /datasets/v3/snapshot/{snapshot_id}:
    get:
      operationId: getSnapshotData
      tags:
        - Web Scraper
      summary: Download snapshot data.
      parameters:
        - name: snapshot_id
          in: path
          required: true
          schema:
            type: string
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [json, ndjson, jsonl, csv]
      responses:
        '200':
          description: Collected records for the snapshot.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '202':
          description: Snapshot not ready yet; still running.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /request:
    post:
      operationId: sendRequest
      tags:
        - SERP
        - Web Unlocker
      summary: SERP API and Web Unlocker request.
      description: >-
        Single endpoint shared by the SERP API and Web Unlocker. The `zone`
        field selects the product (a SERP zone or an unlocker zone). Set
        `async=true` to run asynchronously and retrieve results later.
      parameters:
        - name: async
          in: query
          required: false
          description: Run the request asynchronously.
          schema:
            type: boolean
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnlockRequest'
            examples:
              serp:
                summary: SERP API request
                value:
                  zone: serp_api1
                  url: https://www.google.com/search?q=pizza
                  format: json
              unlocker:
                summary: Web Unlocker request
                value:
                  zone: unlocker1
                  url: https://example.com
                  format: raw
                  method: GET
                  country: us
      responses:
        '200':
          description: Response body (raw HTML/text, JSON, markdown, or screenshot).
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
            text/html:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /zone:
    get:
      operationId: getZone
      tags:
        - Zones
      summary: Get zone status and configuration.
      parameters:
        - name: zone
          in: query
          required: true
          description: Zone name.
          schema:
            type: string
      responses:
        '200':
          description: Zone configuration and status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zone'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: addZone
      tags:
        - Zones
      summary: Add a new proxy zone.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddZoneRequest'
      responses:
        '201':
          description: Zone added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zone'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /browser_sessions/{session_id}:
    get:
      operationId: getBrowserSession
      tags:
        - Browser API
      summary: Get Scraping Browser session metadata.
      description: >-
        Retrieves metadata for a Scraping Browser session. The interactive
        browser control itself runs over the CDP WebSocket endpoint documented
        in asyncapi/brightdata-asyncapi.yml, not this REST call.
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Session metadata.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Bright Data API token from the control panel, sent as
        `Authorization: Bearer <API_KEY>`.
  responses:
    Unauthorized:
      description: Missing or invalid API token.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
  schemas:
    ScraperInput:
      type: array
      description: >-
        Array of input objects passed to a scraper. Most scrapers accept a
        `url` per item; some accept additional discovery parameters.
      items:
        type: object
        properties:
          url:
            type: string
            format: uri
        additionalProperties: true
    TriggerResponse:
      type: object
      description: Response of a trigger call. (Modeled.)
      properties:
        snapshot_id:
          type: string
          description: Identifier used to poll progress and download results.
    ProgressResponse:
      type: object
      description: Snapshot progress. (Modeled.)
      properties:
        snapshot_id:
          type: string
        status:
          type: string
          enum: [running, ready, failed]
        dataset_id:
          type: string
        records:
          type: integer
    UnlockRequest:
      type: object
      required:
        - zone
        - url
        - format
      properties:
        zone:
          type: string
          description: Zone identifier selecting the product configuration.
        url:
          type: string
          format: uri
          description: Complete target URL (must include http/https).
        format:
          type: string
          enum: [raw, json]
          description: Response format.
        method:
          type: string
          default: GET
          description: HTTP method to use against the target.
        country:
          type: string
          description: Two-letter ISO country code for geo-targeting.
        data_format:
          type: string
          enum: [markdown, screenshot]
          description: Optional post-processing of the response body.
        render:
          type: boolean
          description: Enable JavaScript rendering.
    Zone:
      type: object
      description: Zone configuration and status. (Modeled.)
      additionalProperties: true
      properties:
        name:
          type: string
        status:
          type: string
        type:
          type: string
          description: Proxy product type (e.g. residential, datacenter, isp, mobile, unblocker, serp).
    AddZoneRequest:
      type: object
      description: Request body to create a zone. (Modeled.)
      properties:
        zone:
          type: object
          properties:
            name:
              type: string
        plan:
          type: object
          additionalProperties: true