Web Unlocker API

Use the Bright Data Web Unlocker API (98% success rate) to test and unlock websites in real time, bypassing anti-bot protections, proxies and CAPTCHAs.

POST /request

cURL

cURL

curl --request POST \
  --url https://api.brightdata.com/request \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "zone": "web_unlocker1",
    "url": "https://geo.brdtest.com/welcome.txt",
    "format": "raw"
  }'

200

{
  "status_code": 200,
  "headers": {
    "access-control-allow-origin": "*",
    "cache-control": "no-store",
    "content-type": "text/plain; charset=utf-8",
    "date": "Sun, 18 May 2025 20:01:18 GMT",
    "server": "nginx",
    "connection": "close",
    "transfer-encoding": "chunked"
  },
  "body": "\nWelcome to Bright Data! Here are your proxy details\nCountry: US\nLatitude: 37.751\nLongitude: -97.822\nTimezone: America/Chicago\nASN number: 20473\nASN Organization name: AS-VULTR\nIP version: IPv4\n\nCommon usage examples:\n\n[USERNAME]-country-us:[PASSWORD]  // US based Proxy\n[USERNAME]-country-us-state-ny:[PASSWORD]  // US proxy from NY\n[USERNAME]-asn-56386:[PASSWORD]  // proxy from ASN 56386\n[USERNAME]-ip-1.1.1.1.1:[PASSWORD]  // proxy from dedicated pool\n\nTo get a simple JSON response, use https://geo.brdtest.com/mygeo.json .\n\nMore examples on https://docs.brightdata.com/api-reference/introduction\n\n"
}

{
  "error": "Bad Request"
}

{
  "error": "User authentication is required"
}

Related guide: Web Unlocker API Introduction

Bright Data Python SDK

For an easy start using our tools check out our new Python SDK.

Get Started

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

async · boolean

Set this to true for asynchronous

Body

application/json

zone · string · required

Zone identifier that defines your Bright Data product configuration. Each zone contains targeting rules, output preferences, and access permissions. Manage zones at: https://brightdata.com/cp/zones

Example:

"web_unlocker1"

url · string · required

Complete target URL to scrape. Must include protocol (http/https), be publicly accessible.

Example:

"https://geo.brdtest.com/welcome.txt"

format · enum<string> · required

Response format: raw returns HTML content as string, json returns structured data.

Available options: raw, json

Example:

"json"

method · string · default: GET

Method for requesting an HTML via proxy is GET.

Example:

"GET"

country · string

Two-letter ISO 3166-1 country code for proxy location (e.g., us, gb, de, ca, au). If not specified, system auto-selects optimal location based on your zone configuration. List of country codes: https://docs.brightdata.com/general/faqs#where-can-i-see-the-list-of-country-codes

Example:

"us"

data_format · enum<string>

Additional response format transformation: markdown converts HTML content to clean markdown format, screenshot captures a PNG image of the rendered page.

Available options: markdown, screenshot

Example:

"markdown"

render · enum<string>

Set to true to force JavaScript rendering using a browser. Because this flag forces browser use, it can significantly increase response time, so use it only when a page requires JavaScript to load its content.

Available options: true, false

Example:

"true"

debug · boolean · default: false

Set to true to return the x-brd-debug response header, which reports the request ID, traffic counters, billing status, destination IP and peer details for this request. See Debugging Web Unlocker API.

Example:

true

Response

200

application/json

OK

The response is of type object.