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://example.com/",
  "content": true
}'

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://example.com/",
  content: true
};

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://example.com/",
    "content": True
}

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

print(response.json())

Response

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

Examples

BrowserQL Recommended

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.

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.

Get Content:

If you'd like to retrieve the HTML of a page for scraping, set content: true in the JSON payload. Here's a complete example with residential proxy enabled:

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://example.com/",
  "content": true
}'

Response:

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

Get Cookies:

{
  "url": "https://www.example.com/",
  "content": false,
  "cookies": true,
  "screenshot": false,
  "browserWSEndpoint": false,
  "ttl": 0
}

Get Screenshot:

{
  "url": "https://www.example.com/",
  "content": false,
  "cookies": false,
  "screenshot": true,
  "browserWSEndpoint": false,
  "ttl": 0
}

Process the returned HTML with scraping libraries like Scrapy or Beautiful Soup.

Getting a WebSocket Endpoint

The /unblock API can bypass bot detection, then return a WebSocket endpoint and cookies for you to connect with your own Puppeteer/Playwright code.

JSON Request Body:

Set browserWSEndpoint: true, cookies: true, and specify a ttl (time-to-live in milliseconds) to keep the browser session alive for your automation:

{
  "url": "https://example.com",
  "browserWSEndpoint": true,
  "cookies": true,
  "ttl": 30000
}

We recommend using a residential proxy for better bot detection bypass:

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://example.com",
  "browserWSEndpoint": true,
  "cookies": 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": "example.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://example.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://example.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://example.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()

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
Rejecting undesired requests: Block resources with rejectResourceTypes and rejectRequestPattern
Continue on error: Use bestAttempt to continue when async events fail or time out

Quickstart​

Examples​

Data Extraction Modes​

Getting a WebSocket Endpoint​

Connecting to the Browser​

Configuration options​