Your First Async Unlocker API Request

Prerequisites

The following are required:

Enable "Asynchronous requests"

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

Send your first async request

The following request submits an asynchronous 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",
    }'

Replace <API_KEY> and <unlocker-zone-name> with valid values.

Send your first async request

The following request submits an asynchronous 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"
    }'

Replace <API_KEY> and <unlocker-zone-name> with valid values.

Wait and check status

We recommend to wait 20 seconds prior to the first poling request to get the response, 10 seconds for the second pole 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 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!

Documentation Index