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_unlocker1' \
  --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 ', '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> and <unlocker-zone-name> with valid values.

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_unlocker1' \
  --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> and <unlocker-zone-name> with valid values.

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?

No. Our Async mechanism requires you to poll with the request ID and pull your request on demand. Our scrapers do support relaying a payload to a target you provide: if this is a crucial part of your flow, use our google scrapers instead.

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

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