Structured search-engine results (Google, Bing, and others) via a single POST /request call carrying a SERP zone, target search URL, and the desired response format (raw HTML or parsed JSON).
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