Your first async Web Unlocker API request

Prerequisites

The following are required:

Enable "Asynchronous requests"

In the Web Unlocker API zone, under “Advanced settings”, enable the “Asynchronous requests” toggle.

Send your first async request

The following request submits an asynchronous Web Unlocker API job:

cURL

curl --request POST \
  --url 'https://api.brightdata.com/unblocker/req?zone=web_unlocker' \
  --header 'Authorization: Bearer <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=web_unlocker1"

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

  response = requests.post(url, json=payload, headers=headers)

  print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <API_KEY>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: 'https://geo.brdtest.com/welcome.txt',
  })
};

fetch('https://api.brightdata.com/unblocker/req?zone=web_unlocker1', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

Replace <API_KEY> with your API key and web_unlockerwith your Web Unlocker zone name.

Wait and check status

We recommend to wait 20 seconds prior to the first polling request to get the response, 10 seconds for the second poll and 5 for the rest.Bright Data may apply rate limit for excessive poling requests without response.The request returns a response_id used to retrieve results after processing completes.

{
  "response_id": "s4t7w3619285042ra9dke1m8qx"
}

If the request is still processing, the API returns HTTP 202:

HTTP/202

"Request is pending"

Processing time is typically up to 5 minutes and may extend to 8 hours during peak periods.Responses are retained for up to 48 hours from submission time.

Retrieve your results

The following request retrieves the completed result:

curl --silent --compressed \
  "https://api.brightdata.com/unblocker/get_result?&response_id=${RESPONSE_ID}" \
  -H "Authorization: Bearer [API_KEY]" \
  -o results.json

The response body is written to results.json.

Verify the output

Display the saved file:

  cat results.json

The file contains structured JSON results from the Web Unlocker API. For example:

Sample Response

  {
      "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"
  }

Congratulations! If the file contains valid JSON search results, you’re done!

Can Bright Data send the response to a target which I specify?

Not the response body - you always pull that with the response_id. But Bright Data does send a notification to your webhook_url when the job is ready, so no polling loop is needed. See Webhooks setup.

Introduction

Product Guides

Your first async Web Unlocker API request

Can Bright Data send the response to a target which I specify?

​Can Bright Data send the response to a target which I specify?

Can Bright Data send the response to a target which I specify?