Send your first Web Unlocker API request

Make your first request in minutes

Once your Web Unlocker API is created, you can begin unlocking websites immediately. This guide walks you through sending your first successful request, explains the available access methods, and provides ready-to-use examples.

Node.js Example

Python Example

Choose an access method

Bright Data provides two ways to access the Web Unlocker API. Both methods return identical results, but are optimized for different workflows.

Direct API access (recommended)

A pure REST API method for easy access and straightforward integration.

Native proxy-based access

For workflows that rely on proxy-based routing.

Direct API access (recommended)

A simple and RESTful way to interact with Bright Data’s Web Unlocker API. Direct API access abstracts proxy management and allows you to send requests via a central endpoint, ensuring ease of use and straightforward REST API integration.

When to use direct API access

Centralized endpoint: Access Web Unlocker API via a single, RESTful endpoint.
Streamlined direct integration: Eliminating the complexity of managing proxies or routing.
Single API key authentication: Secure and easy to use, replacing the need for username-password management.

Sending your first request

After setting up your Web Unlocker API zone, you can find:

Your API key
A ready-to-use request example
Your zone name

in the Overview tab of your Web Unlocker API zone.

The following is an example of a simple Web Unlocker API cURL request:

Direct API access - cURL

curl -H "Content-Type: application/json" -H "Authorization: Bearer [INSERT_YOUR_API_KEY]" -d "{\"zone\": \"[INSERT_YOUR_WEB_UNLOCKER_ZONE_NAME]\", \"url\": \"[INSERT_YOUR_TARGET_URL]\", \"format\": \"raw\", \"body\": \"{\\\"key\\\":\\\"value\\\"}\"}" https://api.brightdata.com/request

Request breakdown

API Endpoint: https://api.brightdata.com/request
Authorization Header: Authorization: Bearer [INSERT YOUR API key]
- Your API key is found within your Web Unlocker API zone.
Payload:
- zone: Your specific Web Unlocker API zone name.
- url: The target URL you wish to access via Web Unlocker API.
- format: Defines the response format. Use raw to receive the raw response from the target site.
- [Optional] body: Specifies the raw POST payload sent to the target URL. e.g. "body": "{\"key\":\"value\"}"

Generating your Bright Data API key

A Bright Data API key is your secure authentication token for accessing Web Unlocker API via Direct API access. When adding a new Web Unlocker API zone in the control panel, an API key will be generated automatically and can be found within the Overview tab of your zone.

To generate a new API key:

Navigate to Account settings.
Scroll down and click the Add API key button.
Follow the on-screen instructions to complete the process.

We strongly recommend having an expiration date set on your API key for increased security.

The API key will be shown to you on the screen only so make sure you copy and store it in a safe location per your organization’s policies

Native proxy-based access

Proxy-based access is designed for workflows that already use proxy routing. Instead of a REST endpoint, requests are sent through Bright Data’s super proxy.

Which credentials are required

In order to access Web Unlocker, you will need to provide credentials which are comprised of:

Your customer ID
Your Web Unlocker API zone name
Your Web Unlocker API password
Bright Data SSL certificate

Where to find your customer ID

Customer ID can be found in the welcome email you received, or by clicking your account initial letter on the top right screen of your control panel, or by clicking here: Account settings .

Zone name and password

Your zone name and password can be found in the overview tab of your unlocker zone in the control panel.

Bright Data SSL Certificate

Prevent SSL errors by setting up Bright Data SSL certificate

SSL Certificate can be found by clicking “SSL certificate” wizard on your zone’s overview top menu. See further instructions here: SSL certificate. Alternatively, you can ignore SSL errors.

Web Unlocker API: HTTPS Proxy code examples

Once you have your credentials, use the following code to send your first request:

Expand for code examples

curl "http://brdtest.com/myip.json" --proxy brd.superproxy.io:44445 --proxy-user brd-customer-<customer_id>-zone-<zone_name>:<zone_password>

#!/usr/bin/env node

const { ProxyAgent, setGlobalDispatcher } = require('undici');

setGlobalDispatcher(new ProxyAgent('http://brd-customer-<customer_id>-zone-<zone_name>:<zone_password>@brd.superproxy.io:44445'));

(async () => {
  const response = await fetch('http://brdtest.com/myip.json');
  console.log(await response.text());
})();

import pprint
import requests

host = 'brd.superproxy.io'  
port = 44445
username = 'brd-customer-<customer_id>-zone-<zone_name>'
password = '<zone_password>'
proxy_url = f'http://{username}:{password}@{host}:{port}'
proxies = {
  'http': proxy_url,
  'https': proxy_url
}

url = "http://brdtest.com/myip.json"

response = requests.get(url, proxies=proxies)
pprint.pprint(response.json())

<?php

echo 'To enable your free eval account and get CUSTOMER, YOURZONE and YOURPASS, please contact sales@brightdata.com';

$curl = curl_init('http://brdtest.com/myip.json');
curl_setopt($curl, CURLOPT_PROXY, 'http://brd.superproxy.io:44445');
curl_setopt($curl, CURLOPT_PROXYUSERPWD, 'brd-customer-<customer_id>-zone-<zone_name>:<zone_password>');
curl_exec($curl);
?> 

#!/usr/bin/ruby

require 'uri'
require 'net/http'
require 'net/https'

puts 'To enable your free eval account and get CUSTOMER, YOURZONE and YOURPASS, please contact sales@brightdata.com'

uri = URI.parse('http://brdtest.com/myip.json')
proxy = Net::HTTP::Proxy('brd.superproxy.io', 44445, 'brd-customer-<customer_id>-zone-<zone_name>', '<zone_password>')
req = Net::HTTP::Get.new(uri)
result = proxy.start(uri.host,uri.port, :use_ssl  => uri.scheme == 'https') do |http|

http.request(req)

end

puts result.body

using System;
using System.Net;
class Example {
  static void Main() {
    var client = new WebClient();
    client.Proxy = new WebProxy("brd.superproxy.io:44445");
    client.Proxy.Credentials = new NetworkCredential(
      "brd-customer-<customer_id>-zone-<zone_name>",
      "<zone_password>"
    );

    Console.WriteLine(client.DownloadString("http://brdtest.com/myip.json"));
  }
}

package example;
import org.apache.http.HttpHost;
import org.apache.http.client.fluent.*;

public  class Example {
  public  static  void main(String[] args) throws Exception {
    System.out.println(
      "To enable your free eval account and get "
      +"CUSTOMER, YOURZONE and YOURPASS, please contact "
      +"sales@brightdata.com"
    );

    HttpHost proxy = new HttpHost("brd.superproxy.io", 44445);

    String res = Executor.newInstance()
      .auth(proxy, "brd-customer-<customer_id>-zone-<zone_name>", "<zone_password>")
      .execute(Request.Get("http://brdtest.com/myip.json").viaProxy(proxy))
      .returnContent().asString();

    System.out.println(res);
  }
}

#!/usr/bin/perl
print 'To enable your free eval account and get CUSTOMER, YOURZONE and '
.'YOURPASS, please contact sales@brightdata.com';

use LWP::UserAgent;
my  $agent = LWP::UserAgent->new();

$agent->proxy(['http', 'https'], "http://brd-customer-<customer_id>-zone-<zone_name>:<zone_password>\@brd.superproxy.io:44445");
print  $agent->get('http://brdtest.com/myip.json')->content();

Imports System.Net
Module Module1

Sub Main()

Console.WriteLine("To enable your free eval account and get " &
"CUSTOMER, YOURZONE and YOURPASS, please contact " &
"sales@brightdata.com")

Dim Client As  New WebClient
Client.Proxy = New WebProxy("http://brd.superproxy.io:44445")
Client.Proxy.Credentials = New NetworkCredential("brd-customer-<customer_id>-zone-<zone_name>", "<zone_password>")
Console.WriteLine(Client.DownloadString("http://brdtest.com/myip.json"))
End Sub
End Module

The code above uses the residential proxy to send a request to http://brdtest.com/myip.json. It returns your IP information in a JSON format:

Output

{
  "ip": "ALLOCATED_IP",
  "country": "PK",
  "asn": {
    "asnum": 203020,
    "org_name": "HostRoyale Technologies Pvt Ltd"
  },
  "geo": {
    "city": "Islamabad",
    "region": "IS",
    "region_name": "Islamabad",
    "postal_code": "44040",
    "latitude": 33.7233,
    "longitude": 73.0435,
    "tz": "Asia/Karachi",
    "lum_city": "islamabad",
    "lum_region": "is"
  }
}

Now, replace “https://brdtest.com/myip.json” with the website of your choice.

For an interactive display of every Web Unlocker API use case, integration and preference, see the API examples page in the control panel.

Common issues and quick fixes

401 Unauthorized Authentication is missing or invalid. → Verify the Authorization header and your API key.
400 Bad Request The request payload is invalid. → Ensure zone, url and format are all present.
Content looks incomplete → Try another public URL, or review the configuration options.

For the full list of status codes and their causes, see Error codes.

Send your first async request

Asynchronous requests submit a job, return a response_id immediately, and let you collect the result later. Use async when you do not need the unlocked page in the same HTTP response.

Enable asynchronous requests

In your Web Unlocker API zone, open Advanced settings and turn on Asynchronous requests.

Submit the job

Send a POST to the async request endpoint:

curl --request POST \
  --url 'https://api.brightdata.com/unblocker/req?zone=YOUR_ZONE_NAME' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
      "url": "https://geo.brdtest.com/welcome.txt"
    }'

import requests

url = "https://api.brightdata.com/unblocker/req?zone=YOUR_ZONE_NAME"

payload = {"url": "https://geo.brdtest.com/welcome.txt"}
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.post(url, json=payload, headers=headers)
print(response.json()["response_id"])

const response = await fetch(
  "https://api.brightdata.com/unblocker/req?zone=YOUR_ZONE_NAME",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ url: "https://geo.brdtest.com/welcome.txt" }),
  }
);

const data = await response.json();
console.log(data.response_id);

You should see a response_id:

{
  "response_id": "s4t7w3619285042ra9dke1m8qx"
}

Poll for the result

While the job runs, the API returns HTTP 202 with "Request is pending". Wait before polling, or Bright Data may rate-limit excessive empty polls:

Poll	Wait before it
First	20 seconds
Second	10 seconds
Subsequent	5 seconds

Once complete, retrieve the result:

curl --silent --compressed \
  "https://api.brightdata.com/unblocker/get_result?response_id=YOUR_RESPONSE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o results.json

results.json contains the status code, response headers and the unlocked page body:

{
  "status_code": 200,
  "headers": {
    "content-type": "text/plain; charset=utf-8",
    "server": "nginx"
  },
  "body": "Welcome to Bright Data! Here are your proxy details ..."
}

Can Bright Data push the result to my endpoint?

Yes. Instead of polling, configure a webhook and Bright Data delivers the result to a URL you control when the job finishes. See Webhooks setup.

Get started

Data extraction

Web access

AI training data

Proxy networks

Send your first Web Unlocker API request

Make your first request in minutes

Node.js Example

Python Example

Choose an access method

Direct API access (recommended)

Native proxy-based access

Direct API access (recommended)

When to use direct API access

Sending your first request

Request breakdown

Generating your Bright Data API key

Native proxy-based access

Which credentials are required

Where to find your customer ID

Zone name and password

Bright Data SSL Certificate

Web Unlocker API: HTTPS Proxy code examples

Common issues and quick fixes

Send your first async request

Enable asynchronous requests

Submit the job

Poll for the result

Can Bright Data push the result to my endpoint?

​Make your first request in minutes

Node.js Example

Python Example

​Choose an access method

Direct API access (recommended)

Native proxy-based access

​Direct API access (recommended)

​When to use direct API access

​Sending your first request

​Request breakdown

​Generating your Bright Data API key

​Native proxy-based access

​Which credentials are required

​Where to find your customer ID

​Zone name and password

​Bright Data SSL Certificate

​Web Unlocker API: HTTPS Proxy code examples

​Common issues and quick fixes

​Send your first async request

​Enable asynchronous requests

​Submit the job

​Poll for the result

​Can Bright Data push the result to my endpoint?

Make your first request in minutes

Choose an access method

Direct API access (recommended)

When to use direct API access

Sending your first request

Request breakdown

Generating your Bright Data API key

Native proxy-based access

Which credentials are required

Where to find your customer ID

Zone name and password

Bright Data SSL Certificate

Web Unlocker API: HTTPS Proxy code examples

Common issues and quick fixes

Send your first async request

Enable asynchronous requests

Submit the job

Poll for the result

Can Bright Data push the result to my endpoint?