Web Unlocker API

Learn about Bright Data’s API for Web Unlocker, how to send a basic API request, advanced guidelines, and some tips for optimal use. 

Sending a Basic API Request with Web Unlocker

Here's an example of the most simple Web Unlocker request using cURL that returns a JSON:

curl --proxy brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> "https://lumtest.com/myip.json"

You can find your API credentials including Username (Customer_ID), Zone name, and Password, within your proxy zone’s ‘Access parameters’ tab.


Address of our load balancer that will find the fastest Super Proxy for your request


Infrastructure port of our Super Proxies that is used to receive your requests

-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME> 

Username authentication. In its most basic form, it defines your username and what zone you will use for your request. 


Zone password. All zones have passwords that are used for authentication
"https://lumtest.com/myip.json" Replace with your target domain. This is just a placeholder that goes to our server for testing purposes.

For an in-depth interactive display of all the API use cases, integrations, and preferences, please see our API examples page.

Please note: You'll need to sign up (for free), and login to the Bright Data control panel in order to access this API tool. If you add your payment method, you’ll even receive a $5 credit to get you started!

Country Targeting

When using the Unlocker, the same country-targeting functionality as our other proxy networks is available by using the -country-XX parameter, where 'XX' is an ISO 3166-2 country code in lowercase.


curl --proxy brd.superproxy.io:22225 --proxy-user brd-customer-<YOUR_CUSTOMER_ID>-zone-<YOUR_ZONE>-country-<2-LETTER ISO CODE>:<PASSWORD> -k "<Target site>"

EU Specific Targeting

Web Unlocker allows random peer selection from EU-member countries via the use of the

-country-eu parameter, this can improve success rates over targeting just one country, while still keeping the peer within the EU.

Mobile User Agent Targeting

By default, Web Unlocker uses desktop-specific user agents for your requests. To use a mobile user agent instead, simply append -ua-mobile to your request. 

Using Web Unlocker for Asynchronous Requests

Send requests without waiting for a response. Collect results via a designated endpoint or a webhook.

Initiate an Asynchronous Request

  • Create a request via the API interface
RESPONSE_ID=`curl -i --silent --compressed "https://api.brightdata.com/unblocker/req?customer=<Accound ID>&zone=<ZONE>" -H "Content-Type: application/json" -H "Authorization: Bearer <API token>" -d "{\"flags\":\"country-de\",\"url\":\"<Target site>\"}" | sed -En 's/^x-response-id: (.*)/\1/p' | tr -d '\r'`
  • Get the response (same for both proxy and API interface):
curl -v --compressed "https://api.brightdata.com/unblocker/get_result?customer=<YOUR_CUSTOMER_ID>&zone=<YOUR_ZONE>&response_id=${RESPONSE_ID}" -H "Authorization: Bearer <API token>"

Adjust your Web Unlocker async settings

  1. Sign in to Bright Data's control panel
  2. Navigate to the ‘My proxies page’.
  3. Click on your Web Unlocker zone
  4. On your zone’s configuration page, click on ‘Advanced options, and enable ‘Asynchronous requests’

  1. Once you've enabled ‘Asynchronous requests’, you’ll be able to configure your WebHook URL (address to deliver the results to) and your HTTP method to deliver the response (GET or POST).


 6. Once you've configured your requirements, click ‘Save’.

Account Management API

Please see the following section for different API options available within account management, such as: Adding/deleting a zone, adding an IP to a whitelist/blacklist, and more

Bright Data API token

Bright Data API token is a secure method to replace your credentials (i.e. email address and password) when sending requests to Bright Data via API. The API token is required in order to use the API, keeping your account's credentials safe and secure at all times. 

Create an API token

  1. Sign in to Bright Data's control panel 
  2. Navigate to your account settings page - Click on the Settings icon (bottom left) and then 'Account settings'


  1. Click on ‘Add token’

  1. Set token expiration date (or choose ‘Unlimited’), permissions and select the user to generate the token to, then click ‘Save’

  1. Once your token has been generated make sure you save it, as it’s available for a one-time view only!

    Note: Once you’ve created your token, you won’t be able to view it again, however, you can still refresh it, change its expiration date and revoke it at any time.

Was this article helpful?