Headless Browser

A cloud-based headless browser with built-in adaptive security, CAPTCHA management, and residential proxies. Test it with code samples and customize with advanced features.

Headless Browser allows you to run and control remote instances for browser-based automation, testing, and web scraping without managing them locally. It provides built-in adaptive security, automatic CAPTCHA handling, geotargeting, integrated residential proxies, session recording, sticky sessions, and persistent profiles.

Supported libraries

Headless Browser works with any library that supports the Chrome DevTools Protocol (CDP), including:

Playwright (Python and Node.js)
Puppeteer (Node.js)
Other CDP-compatible automation frameworks

Connection details

Protocol

wss:// (WebSocket Secure)

Host (Chromium)

ubc.oxylabs.io

Authentication

In the URL, user info – wss://USERNAME:PASSWORD@host. Must include username suffix token (e.g. user_ab12). Header-based authentication not supported.

Transport

CDP – chromium.connectOverCDP (Playwright) / puppeteer.connect (Puppeteer)

Domains

oxylabs.io – connection endpoints you authenticate and connect to (e.g. ubc.oxylabs.io) headlesify.io – dashboard, session inspection and recordings (e.g. dashboard.headlesify.io, vnc.headlesify.io).

Rate limits

100 concurrent sessions, 10 session per second. See more.

Features

Oxylabs Headless Browser includes built-in, cloud-native features designed to be used through query parameters to your WebSocket connection URL.

CAPTCHA Handling

Automatic, real-time CAPTCHA handling and monitoring.

Proxy & Geolocation Targeting

Route sessions through specific countries, states, or cities.

Device Emulation

Emulate device-specific fingerprints and viewports.

Session Inspection (VNC)

Monitor live headless browser sessions.

Session Recording

Record browser sessions in video format.

Persistent Sessions

Create and manage sticky browser instances.

Persistent Profiles

Save and restore cookies/localStorage across sessions. (Activation required)

Passing parameters

All features are enabled and configured by appending query parameters directly to your WebSocket Secure endpoint by chaining multiple features together using ampersands (&).

# Example: Connecting to Chrome with US Geolocation, CAPTCHA handling, and Live VNC Stream
wss://USER:PASS@ubc.oxylabs.io?p_cc=US&solve_captcha=true&o_vnc=true

Code examples

Below are basic examples to initialize a cloud-hosted browser session:

from playwright.sync_api import sync_playwright

username = "USERNAME" # include any account suffix
password = "PASSWORD"
endpoint = "ubc.oxylabs.io"
browser_url = f"wss://{username}:{password}@{endpoint}?p_cc=US"

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(browser_url)
    page = browser.new_page()
    page.goto("https://ip.oxylabs.io/location")
    print(page.title())
    browser.close()

process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; //For testing only
import { chromium } from "playwright";

const username = "USERNAME";
const password = "PASSWORD";
const endpoint = "ubc.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?p_cc=US`;

(async () => {
    const browser = await chromium.connectOverCDP(browserUrl);
    const ctx = browser.contexts()[0] || (await browser.newContext());
    const page = ctx.pages()[0] || (await ctx.newPage());
    await page.goto("https://ip.oxylabs.io/location");
    console.log(await page.title());
    await browser.close();
})();

process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; //For testing only
import puppeteer from "puppeteer";

const username = "USERNAME";
const password = "PASSWORD";
const endpoint = "ubc.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?p_cc=US`;

(async () => {
    const browser = await puppeteer.connect({ browserWSEndpoint: browserUrl });
    const page = await browser.newPage();
    await page.goto("https://ip.oxylabs.io/location");
    console.log(await page.title());
    await browser.close();
})();

Note: Examples use USERNAME and PASSWORD for readability only. In real projects, load them from environment variables (e.g. process.env.OXYLABS_USERNAME / process.env.OXYLABS_PASSWORD) via a .env file.

JavaScript: Use NODE_TLS_REJECT_UNAUTHORIZED="0" flag before requiring Playwright in Node.js if you encounter TLS/certificate errors. For local testing only. In production, scope trust to the specific connection or add the provider’s CA certificate to your trust store instead.

Parameter reference

Parameter

Description

Type

p_cc

Country geolocation in ISO 3166-1 alpha-2 2-letter code (e.g., US, DE).

string

p_state

State geolocation in lowercase (e.g., texas). Overrides p_cc if both are used. Supported states list.

string

p_city

City geolocation, lowercase, _ for spaces (e.g., new_york). p_cc / p_state required.

string

p_device

Set device fingerprints, viewports, and user-agents. Supports desktop (default) and mobile.

string

solve_captcha

Automatic, real-time CAPTCHA solving on page loads. Default: true.

boolean

record

Record headless session video. Default: false.

boolean

record_name

Name the recording for easy lookup (^[a-zA-Z0-9_-]{1,64}$).

string

session_name

Sticky sessions – reconnects to the same live remote browser (^[A-Za-z0-9-]{3,36}$, supports hyphens, no underscores). Max TTL – 24h.

string

keep_alive

Closes the remote browser instance on client disconnect when set to false. Default: true.

boolean

o_profile

Persistent profiles – save/restore cookies and localStorage with a named profile (^[A-Za-z0-9_-]{1,36}$).

string

o_profile_save

Persistent profiles – force profile save mid-session. Default: true.

boolean

proxy_resi_ses_id

Custom session ID to pin residential exit IP across sessions (^[A-Za-z0-9]{3,36}$).

string

proxy_resi_ses_time

Duration to hold the pinned residential proxy exit IP in minutes. Min 1, max 1440 (24h).

integer

– available after manual activation for your account. Learn more.

Recommended setup

Optimizing traffic

Scraping dynamic pages often causes the browser to download unnecessary assets such as heavy media, tracking scripts, images, and fonts. This consumes bandwidth and slows down execution times.

You can intercept and abort these requests programmatically before they consume resources:

# Abort heavy assets to save bandwidth and improve speeds
def block_resources(route):
    if route.request.resource_type in ["image", "stylesheet", "media", "font"]:
        route.abort()
    else:
        route.continue_()

page.route("**/*", block_resources)

// Abort heavy assets to save bandwidth and improve speeds
await page.route("**/*", (route) => {
    const type = route.request().resourceType();
    if (["image", "stylesheet", "media", "font"].includes(type)) {
        return route.abort();
    }
    return route.continue();
});

Error handling and retries

Network hiccups and 10-sessions-per-second rate limit mean a single connectOverCDP call can fail transiently. Wrap connection in a retry with exponential backoff, and cap each attempt with a timeout. The example below uses standard Playwright API:

const { chromium } = require("playwright");

const MAX_RETRIES = 5;
const BASE_DELAY_MS = 1000;

async function connectWithRetry(endpoint, { maxRetries = MAX_RETRIES } = {}) {
    let lastError;
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
            // Cap how long a single connection attempt may take.
            return await chromium.connectOverCDP(endpoint, { timeout: 60_000 });
        } catch (err) {
            lastError = err;
            // Exponential backoff with jitter — backs off when you hit the
            // 10-new-sessions/second rate limit instead of hammering the endpoint.
            const delay = BASE_DELAY_MS * 2 ** attempt + Math.random() * 250;
            console.warn(
                `connect attempt ${attempt + 1} failed: ${err.message}; ` +
                `retrying in ${Math.round(delay)}ms`
            );
            await new Promise((resolve) => setTimeout(resolve, delay));
        }
    }
    throw lastError;
}

Resource cleanup

Always close the browser when you are done, even if your automation throws midway. Use a try { ... } finally { ... } block so cleanup runs on every path:

const browser = await connectWithRetry(endpoint);
try {
    const ctx = browser.contexts()[0] || (await browser.newContext());
    const page = ctx.pages()[0] || (await ctx.newPage());
    await page.goto("https://ip.oxylabs.io/location");
    // ... your automation ...
} finally {
    // Runs even if the block above throws. Without this, a session left open
    // after an exception lingers and counts against your 100 concurrent-session limit.
    await browser.close();
}

If an exception occurs between connect and close and you do not clean up, the remote session stays open and consumes one of your 100 concurrent sessions until it is reclaimed. Leaking sessions under load can exhaust the limit and block new connections.

Need a feature enabled?

Some Headless Browser features are off or restricted by default. To access them, contact Oxylabs support (live chat or email) or your Dedicated Account Manager:

Persistent profiles – gain access to the feature and o_profile parameters.
More profiles – raise account's max_profiles cap for persistent profiles.
Restricted targets – unlock more target categories via KYC process.
Higher rate limits – increase beyond 100 concurrent sessions / 10 per second.

PreviousBilling Information NextCAPTCHA Handling

Last updated 21 days ago

Was this helpful?