Unblock API

Bypass CAPTCHAs and bot detection, then return content, cookies, screenshots, or a browserWSEndpoint for custom automation. Works best with our Browserless Residential Proxy Service.

Endpoint

Method: POST
Path: /unblock
Auth: token query parameter (?token=)
Content-Type: application/json
Response: application/json

See the OpenAPI reference for complete details.

Quickstart

cURL
Javascript
Python

curl --request POST \
  --url 'https://production-sfo.browserless.io/unblock?token=YOUR_API_TOKEN_HERE&proxy=residential' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://turo.com/",
  "content": true,
  "cookies": false,
  "screenshot": false,
  "browserWSEndpoint": false
}'

const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/unblock?token=${TOKEN}&proxy=residential`;
const headers = {
  "Content-Type": "application/json"
};

const data = {
  url: "https://turo.com/",
  content: true,
  cookies: false,
  screenshot: false,
  browserWSEndpoint: false
};

const fetchContent = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
  });

  const content = await response.json();
  console.log(content);
};

fetchContent();

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/unblock?token={TOKEN}&proxy=residential"
headers = {
    "Content-Type": "application/json"
}

data = {
    "url": "https://turo.com/",
    "content": True,
    "cookies": False,
    "screenshot": False,
    "browserWSEndpoint": False
}

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

print(response.json())

Response

{
  "content": "<!DOCTYPE html><html>...</html>",
  "cookies": [],
  "screenshot": null,
  "browserWSEndpoint": null
}

Data Extraction Modes

The Unblock API is optimized to return only the data you request. Set fields to true for the data you need, and false for everything else to reduce execution time and resource usage.

Return Content

Returns the full HTML of the page after the site has been unblocked and anti-bot measures have been bypassed. Use this to scrape page content with libraries like Scrapy or Beautiful Soup.

JSON body:

{
  "url": "https://turo.com/",
  "content": true,
  "cookies": false,
  "screenshot": false,
  "browserWSEndpoint": false
}

cURL:

curl -s -X POST "https://production-sfo.browserless.io/unblock?token=YOUR_API_TOKEN_HERE&proxy=residential" -H "Content-Type: application/json" -d '{"url":"https://news.ycombinator.com/","content":true,"cookies":false,"screenshot":false,"browserWSEndpoint":false}'

Response:

{
  "content": "<!DOCTYPE html><html>...</html>",
  "cookies": [],
  "screenshot": null,
  "browserWSEndpoint": null
}

Return Cookies

Returns an array of cookie objects set by the site after unblocking. Each cookie includes properties such as name, value, domain, path, secure, httpOnly, and expiration details. Useful for maintaining authenticated sessions or passing cookies into subsequent requests.

JSON body:

{
  "url": "https://turo.com/",
  "content": false,
  "cookies": true,
  "screenshot": false,
  "browserWSEndpoint": false
}

cURL:

curl -s -X POST "https://production-sfo.browserless.io/unblock?token=YOUR_API_TOKEN_HERE&proxy=residential" -H "Content-Type: application/json" -d '{"url":"https://news.ycombinator.com/","content":false,"cookies":true,"screenshot":false,"browserWSEndpoint":false}'

Response:

{
  "content": null,
  "cookies": [
    {
      "name": "session_id",
      "value": "XYZ123",
      "domain": "turo.com",
      "path": "/",
      "secure": true,
      "httpOnly": true
    }
  ],
  "screenshot": null,
  "browserWSEndpoint": null
}

Return Screenshot

Returns a base64-encoded screenshot of the page after anti-bot measures have been bypassed. You can decode the base64 string to save it as a PNG image.

JSON body:

{
  "url": "https://turo.com/",
  "content": false,
  "cookies": false,
  "screenshot": true,
  "browserWSEndpoint": false
}

cURL:

curl -s -X POST "https://production-sfo.browserless.io/unblock?token=YOUR_API_TOKEN_HERE&proxy=residential" -H "Content-Type: application/json" -d '{"url":"https://news.ycombinator.com/","content":false,"cookies":false,"screenshot":true,"browserWSEndpoint":false}'

Response:

{
  "content": null,
  "cookies": [],
  "screenshot": "iVBORw0KGgoAAAANSUhEUgAA...",
  "browserWSEndpoint": null
}

Return WebSocket Endpoint

The /unblock API can bypass bot detection, then return a WebSocket endpoint and cookies for you to connect with your own Puppeteer or Playwright code. Set browserWSEndpoint: true, cookies: true, and specify a ttl (time-to-live in milliseconds) to keep the browser session alive for your automation.

JSON body:

{
  "url": "https://turo.com/",
  "content": false,
  "cookies": true,
  "screenshot": false,
  "browserWSEndpoint": true,
  "ttl": 30000
}

cURL:

curl -s -X POST "https://production-sfo.browserless.io/unblock?token=YOUR_API_TOKEN_HERE&proxy=residential" -H "Content-Type: application/json" -d '{"url":"https://news.ycombinator.com/","content":false,"cookies":true,"screenshot":false,"browserWSEndpoint":true,"ttl":30000}'

Response:

{
  "browserWSEndpoint": "wss://production-sfo.browserless.io/p/53616c74...646b292c/devtools/browser/102ea3e9-74d7-42c9-a856-1bf254649b9a",
  "cookies": [
    {
      "name": "session_id",
      "value": "XYZ123",
      "domain": "turo.com",
      "path": "/",
      "secure": true,
      "httpOnly": true
    }
  ],
  "content": null,
  "screenshot": null
}

Connecting to the Browser

After receiving the response with the browserWSEndpoint and cookies, you can use Puppeteer, Playwright, or another CDP library to connect to the browser instance and inject the cookies to continue your automation:

Puppeteer
Playwright

import puppeteer from "puppeteer-core";

const TOKEN = "YOUR_API_TOKEN_HERE";

const unblock = async (url) => {
  const response = await fetch(
    `https://production-sfo.browserless.io/unblock?token=${TOKEN}&proxy=residential`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        url: url,
        browserWSEndpoint: true,
        cookies: true,
        ttl: 30000
      })
    }
  );
  return await response.json();
};

// Get the WebSocket endpoint after bot detection bypass
const { browserWSEndpoint, cookies } = await unblock("https://turo.com/");

// Connect to the browser
const browser = await puppeteer.connect({
  browserWSEndpoint: `${browserWSEndpoint}?token=${TOKEN}`
});
const page = (await browser.pages())[0];

// Inject cookies if needed
// await page.setCookie(...cookies);

await page.screenshot({ path: "screenshot.png" });
await browser.close();

Javascript
Python

import playwright from "playwright-core";

const TOKEN = "YOUR_API_TOKEN_HERE";

const unblock = async (url) => {
  const response = await fetch(
    `https://production-sfo.browserless.io/unblock?token=${TOKEN}&proxy=residential`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        url: url,
        browserWSEndpoint: true,
        cookies: true,
        ttl: 30000
      })
    }
  );
  return await response.json();
};

// Get the WebSocket endpoint after bot detection bypass
const { browserWSEndpoint, cookies } = await unblock("https://turo.com/");

// Connect to the browser
const browser = await playwright.chromium.connect(`${browserWSEndpoint}?token=${TOKEN}`);
const context = await browser.newContext();
const page = await context.newPage();

// Inject cookies if needed
// await context.addCookies(cookies);

await page.screenshot({ path: "screenshot.png" });
await browser.close();

from playwright.sync_api import sync_playwright
import requests

TOKEN = "YOUR_API_TOKEN_HERE"

def unblock(url):
    response = requests.post(
        f"https://production-sfo.browserless.io/unblock?token={TOKEN}&proxy=residential",
        headers={"Content-Type": "application/json"},
        json={
            "url": url,
            "browserWSEndpoint": True,
            "cookies": True,
            "ttl": 30000
        }
    )
    return response.json()

with sync_playwright() as p:
    # Get the WebSocket endpoint after bot detection bypass
    response = unblock("https://turo.com/")
    browserWSEndpoint = response["browserWSEndpoint"]
    cookies = response.get("cookies", [])

    # Connect to the browser
    browser = p.chromium.connect(f"{browserWSEndpoint}?token={TOKEN}")
    context = browser.new_context()
    page = context.new_page()

    # Inject cookies if needed
    # context.add_cookies(cookies)

    page.screenshot(path="screenshot.png")
    browser.close()

Still getting blocked?

For advanced bot detection and CAPTCHA solving, we recommend using BrowserQL with the solve mutation. It automatically detects and solves CAPTCHAs (reCAPTCHA, Cloudflare, and others) with built-in stealth capabilities.

The /unblock API works best when combined with our Browserless Residential Proxy Service.

Configuration options

The /unblock API supports shared request configuration options that apply across REST endpoints:

Waiting for things: Wait for events, functions, selectors, or timeouts before returning the response
Navigation options: Customize navigation behavior with gotoOptions
Continue on error: Use bestAttempt to continue when async events fail or time out

Quickstart​

Data Extraction Modes​

Return Content​

Return Cookies​

Return Screenshot​

Return WebSocket Endpoint​

Connecting to the Browser​

Still getting blocked?​

Configuration options​

Quickstart

Data Extraction Modes

Return Content

Return Cookies

Return Screenshot

Return WebSocket Endpoint

Connecting to the Browser

Still getting blocked?

Configuration options