Captcha Solver API Proxy API Fingerprint API Browser API

Browser API: User Documentation

Browser API is 2Captcha's cloud browser for automating websites that require a real browser: JavaScript rendering, clicks, forms, scrolling, geo-dependent content, proxies, and CAPTCHA handling.

You connect to the remote browser using a ready-to-use CDP WebSocket URL from your 2Captcha dashboard and control it through familiar tools: Playwright, Puppeteer, or any other client that supports the Chrome DevTools Protocol.

You don't need to run Chrome on your own server, maintain browser infrastructure, manually build proxy strings, or figure out the connection format. All the main parameters are assembled in the Dashboard.

Introduction
Quick Start
5 Minute How-To
Configuration
Features
CDP Functions
- Standard CDP / browser automation
- Custom CDP helpers
Code Examples
Troubleshooting
FAQs

Introduction

What is Browser API

Browser API runs a browser session in the 2Captcha cloud. Your code connects to this session via a WebSocket URL and controls the page exactly as if the browser were running locally.

A typical workflow:

Open the Browser API Dashboard.
Select a country and proxy mode.
Copy the ready-to-use CDP URL.
Paste it into Playwright or Puppeteer.
Your script opens the site, performs actions, and retrieves the result.
If needed, you can watch the session via Live.

When to use Browser API

Browser API is the right choice when a plain HTTP request is not enough.

Use it when a website:

renders content via JavaScript;
loads data after the page has loaded;
requires clicks, text input, scrolling, or waiting for elements;
shows different pages in different countries;
uses checks, redirects, dynamic forms, or CAPTCHA;
works unreliably with a simple request via curl, requests, fetch, or similar tools.

What you get

With Browser API you can:

run remote browser sessions;
connect to them through Playwright, Puppeteer, and CDP clients;
choose the session country;
use your own external proxy or a 2Captcha proxy account;
generate a single CDP URL or a list of URLs for parallel work;
watch active sessions via Live;
solve CAPTCHAs in browser-based scenarios;
track browser traffic consumption.

Quick Start

This section will help you launch your first browser session quickly.

1. Open the Browser API Dashboard

Go to the Browser API section and open the Dashboard.

The Dashboard contains:

Traffic — browser traffic balance;
Add / Buy traffic — top up browser traffic;
Connection setting — settings for the future CDP URL;
CDP URL preview — ready-to-use connection string;
Copy — copy the CDP URL;
Generate list — generate a list of CDP URLs;
Browser Logins — current profiles and sessions;
Live — view an active browser session.

2. Check browser traffic

Before launching, make sure you have browser traffic available.

Browser traffic is consumed when the cloud browser loads pages and resources: HTML, JavaScript, CSS, images, fonts, page API requests, and other network requests.

If you don't have enough traffic, click Add or Buy browser traffic, choose the amount, and confirm the purchase.

Important: browser traffic and proxy traffic are separate balances. Browser traffic is consumed by the cloud browser. Proxy traffic belongs to the proxy service and is paid for separately.

3. Select a country

In the Country field, choose the country the session should run from.

For example:

text Copy

de — Germany
us — United States
fr — France

The selected country will be used in the CDP URL. If a 2Captcha proxy account is selected, the same country will also be applied to the proxy session.

4. Choose a proxy mode

Two main modes are available.

Custom proxy — use this if you have an external proxy and want to enter it manually.

Proxy account — use this if you want to pick a proxy account from your 2Captcha dashboard. In this mode, host, port, login, and password are filled in automatically.

5. Copy the CDP URL

Once you've chosen your settings, the Dashboard immediately shows the ready CDP URL.

Click Copy and paste the URL into your code.

Example CDP URL:

text Copy

ws://10001-pid-profilea3f9k-zone-country-de-proxy-...:cloud_browser_pass@cb.2captcha.com:9222

The CDP URL contains browser access credentials, so treat it as a secret: do not publish it in repositories, logs, tickets, or chats.

6. Connect from your code

Example in Python + Playwright:

python Copy

import asyncio
from playwright.async_api import async_playwright

CDP_URL = "ws://..."  # paste the CDP URL from the Dashboard
TARGET_URL = "https://example.com"

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(CDP_URL)
        page = await browser.new_page()

        await page.goto(TARGET_URL, timeout=120_000)
        print(await page.title())

        await browser.close()

asyncio.run(main())

If the script connects to the browser, opens the page, and prints the title — Browser API is working.

5 Minute How-To

A scenario to test Browser API in just a few minutes.

What you need before you start

Make sure you have:

a 2Captcha account;
access to the Browser API section;
browser traffic on your balance;
Playwright or Puppeteer installed;
a test URL to open.

Step 1. Choose a test page

For your first run, it's best to pick a page that reliably opens in a browser.

Examples of test tasks:

get the page title;
wait for an element to appear;
take a screenshot;
get the HTML after JavaScript has executed.

Step 2. Generate a CDP URL

In the Dashboard, select:

Country;
proxy mode: Custom proxy or Proxy account;
the proxy account you need or external proxy details.

Copy the CDP URL with Copy.

Step 3. Run the script

Paste the CDP URL into the Playwright or Puppeteer example and run the code.

Use a timeout of at least 120 seconds, because some websites take a long time to load due to JavaScript, redirects, checks, and heavy resources.

Step 4. Check the result

A successful check means the script:

connected to the cloud browser;
opened a new page;
navigated to the target URL;
waited for the page to load;
got the title, HTML, or screenshot;
closed the browser after finishing.

Step 5. Open Live on errors

If the script hangs, the page is empty, or an element isn't found, click Live next to the relevant profile.

Live shows what the cloud browser actually sees: the page, a redirect, a form, a CAPTCHA, a loading error, or the content you need.

Configuration

The Configuration section describes the settings the user chooses before starting a browser session.

Dashboard

The Dashboard is the main Browser API page. This is where you prepare connections and monitor active sessions.

In the Dashboard you can:

check your browser traffic balance;
top up browser traffic;
choose the session country;
choose a proxy mode;
generate a CDP URL;
copy a single URL;
generate a list of URLs;
open an active session through Live;
view active browser profiles, runtime, and traffic usage.

CDP URL Generator

The CDP URL Generator builds the connection string automatically. You don't need to manually encode the proxy, generate a profile ID, or check the WebSocket URL format.

The generator updates the preview whenever any form field changes.

The basic CDP URL format:

text Copy

ws://{user_id}-pid-{profile_id}-zone-country-{country_code}-proxy-{proxy_base64url}:{password}@cb.2captcha.com:9222

What you need to know:

user_id is filled in automatically;
profile_id is created automatically;
country_code is taken from the Country dropdown;
proxy_base64url is generated from the selected proxy;
password is set by the service;
the ready URL should be copied via Copy.

You normally don't need to edit the CDP URL manually.

Custom Proxy Mode

The Custom proxy mode is for when you want to use your own external proxy.

Form fields:

Country — the session country;
Protocol — http, https, or socks5;
Host — proxy address;
Port — proxy port;
Login — proxy login, if required;
Password — proxy password, if required.

If the proxy doesn't require authentication, leave Login and Password empty.

The Dashboard will build the proxy URL and add it to the CDP URL.

Proxy format with authentication:

text Copy

{protocol}://{login}:{password}@{host}:{port}

Proxy format without authentication:

text Copy

{protocol}://{host}:{port}

Example:

text Copy

http://myuser:mypass@proxy.example.com:8080

After selecting a country and proxy, the resulting CDP URL will look like this:

text Copy

ws://10001-pid-profilea3f9k-zone-country-de-proxy-aHR0cDovL215dXNlcjpteXBhc3NAcHJveHkuZXhhbXBsZS5jb206ODA4MA:cloud_browser_pass@cb.2captcha.com:9222

A custom proxy applies to sessions started with a specific CDP URL. It is not stored as a permanent profile setting.

Proxy Account Mode

The Proxy account mode is for when you want to use a proxy account from your 2Captcha dashboard.

Form fields:

Proxy account — proxy account from the list;
Country — session country.

In this mode you don't need to enter host, port, login, or password. The Dashboard pulls the proxy account data and builds the CDP URL automatically.

A separate session ID is created for the proxy session. This helps keep sessions separate and prevents parallel runs from mixing.

Proxy session lifetime is 30 minutes.

Example proxy URL before being added to the CDP URL:

text Copy

http://proxy_username-zone-custom-region-de-session-KSZIcwVJd-sessTime-30:proxy_password@eu.proxy.2captcha.com:2334

Example of the resulting CDP URL:

text Copy

ws://10001-pid-profilem8z1q-zone-country-de-proxy-aHR0cDovL3Byb3h5X3VzZXJuYW1lLXpvbmUtY3VzdG9tLXJlZ2lvbi1kZS1zZXNzaW9uLUtTWkljd1ZKZC1zZXNzVGltZS0zMDpwcm94eV9wYXNzd29yZEBldS5wcm94eS4yY2FwdGNoYS5jb206MjMzNA:cloud_browser_pass@cb.2captcha.com:9222

Country

Country sets the geography of the browser session.

The country is used in two places:

in the CDP URL: zone-country-{country_code};
in Proxy account mode: in the proxy login as region-{country_code}.

The values always match. If Germany is selected, both the browser session and the proxy session use de. If the US is selected — us.

Choose the country before copying the CDP URL. If you changed the country after copying, copy the URL again.

Generate list

Generate list is for when you need to create several CDP URLs at once.

Use it for:

parallel workers;
task queues;
independent browser sessions;
running multiple scenarios with the same country;
bulk page checks;
preparing URLs for different processes or servers.

How to use it:

Configure Country and proxy mode.
Click Generate list.
Specify how many URLs you want.
Click Generate.
Copy the list with Copy all.

Each URL is printed on a new line.

In Custom proxy mode, each URL gets a new profile ID but uses the same proxy.

In Proxy account mode, each URL gets a new profile ID and a new session ID.

Don't use the same CDP URL for several independent parallel tasks. If each task needs its own session, generate a list.

Browser Logins

A browser profile is the profile of a browser session.

The Browser Logins table shows:

CDP URL — the connection string;
Copy — copy the CDP URL;
Live — view the active session;
Created At — start time;
Duration — how long the session has been running;
Traffic — browser traffic used by the session.

If you've hit the limit of active profiles, disable or delete unused ones and create a new one.

Traffic

Browser traffic is the traffic consumed by the cloud browser.

Traffic is shared across all browser profiles in your account. It is not tied to a specific profile.

The Dashboard shows your current balance. In the Statistics section you can view usage by period and by profile.

To reduce traffic usage:

close the browser after the scenario finishes;
don't open unnecessary tabs;
avoid repeated navigations when unnecessary;
block heavy resources if they aren't required for the task;
only use Generate list for genuinely independent sessions.

Features

Captcha Solver

Browser API helps you work with pages where a CAPTCHA appears.

In a typical scenario, you start a browser session, open the page, and continue once the check has been passed. If a CAPTCHA appears during the scenario, you can monitor it via Live and through CDP commands.

When it's useful:

a form or page only opens after the CAPTCHA;
the CAPTCHA appears later, after a click or form submission;
you need to automate a scenario without manual intervention;
you need to see the solving status in code.

Example of checking status via a CDP helper:

javascript Copy

const client = await page.target().createCDPSession();
const { status } = await client.send('Captcha.solve', { detectTimeout: 30000 });
console.log(`Captcha status: ${status}`);

If the scenario doesn't move forward, open Live and check what stage the browser is at.

Geolocation targeting

Geolocation targeting lets you run sessions from the country you need.

It's useful when a website:

shows different prices in different countries;
changes language or currency;
serves different versions of pages;
restricts access by region;
requires checking content availability from a specific country.

In the Dashboard, choose Country. The country code is automatically embedded in the CDP URL.

Example fragment of a CDP URL for Germany:

text Copy

zone-country-de

In Proxy account mode, the same country is used in the proxy session:

text Copy

region-de

Playground

The Playground is a place to quickly test Browser API without setting up a full project.

Use the Playground to:

run a ready-made example;
check a CDP URL;
open a test page;
view results without spending time on environment setup;
quickly verify that the country, proxy, and session are working.

After a successful check, move the same CDP URL and scenario into your own code.

Live debugging

Live debugging lets you watch an active browser session in your browser.

Open Live when you need to understand:

whether the page loaded;
whether the browser sees the content you expect;
whether a CAPTCHA appeared;
whether a click worked;
where a redirect went;
why an element isn't found;
which country or proxy was applied.

Live doesn't replace your automation code, but it speeds up debugging considerably.

Parallel sessions

Browser API supports independent parallel sessions.

For parallel runs, use Generate list. Each URL from the list can be handed to a separate worker or process.

Recommendations:

one CDP URL = one independent browser session;
generate multiple URLs for multiple tasks;
don't reuse the same URL across different workers at the same time;
watch your active profile limit and traffic usage.

CDP Functions

Standard CDP / browser automation

Once connected via the CDP URL, you can use the normal Playwright or Puppeteer commands.

Common actions:

open a page;
wait for a selector;
click an element;
fill a field;
run JavaScript on the page;
get the HTML;
take a screenshot;
intercept requests;
work with cookies;
close the browser.

Examples:

javascript Copy

await page.goto('https://example.com', { timeout: 120000 });
await page.waitForSelector('body', { timeout: 30000 });
console.log(await page.title());

python Copy

await page.goto('https://example.com', timeout=120_000)
await page.wait_for_selector('body', timeout=30_000)
print(await page.title())

Custom CDP helpers

Custom helpers are used for Browser API features that are easier to call via CDP.

Typical examples:

get an inspect link for the active session;
check or trigger CAPTCHA solving;
get service info about the session;
manage additional browser session settings.

Example of opening an inspect link via CDP:

javascript Copy

const client = await page.target().createCDPSession();
const { frameTree: { frame } } = await client.send('Page.getFrameTree');
const { url } = await client.send('Page.inspect', { frameId: frame.id });
console.log(`Inspect session: ${url}`);

If your task only needs the regular Playwright or Puppeteer API, you don't have to use custom helpers.

Code Examples

Playwright Python

python Copy

import asyncio
from playwright.async_api import async_playwright

CDP_URL = "ws://..."  # copy from the Browser API Dashboard
TARGET_URL = "https://example.com"

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(CDP_URL)
        page = await browser.new_page()

        await page.goto(TARGET_URL, timeout=120_000)
        await page.wait_for_selector("body", timeout=30_000)

        print("Title:", await page.title())
        html = await page.content()
        print("HTML length:", len(html))

        await page.screenshot(path="page.png", full_page=True)
        await browser.close()

asyncio.run(main())

Puppeteer Node.js

javascript Copy

const puppeteer = require('puppeteer-core');

const CDP_URL = 'ws://...'; // copy from the Browser API Dashboard
const TARGET_URL = 'https://example.com';

(async () => {
  const browser = await puppeteer.connect({
    browserWSEndpoint: CDP_URL,
  });

  try {
    const page = await browser.newPage();
    await page.goto(TARGET_URL, { timeout: 120000 });
    await page.waitForSelector('body', { timeout: 30000 });

    console.log('Title:', await page.title());
    console.log('HTML length:', (await page.content()).length);

    await page.screenshot({ path: 'page.png', fullPage: true });
  } finally {
    await browser.close();
  }
})();

Working with a list of CDP URLs

If you generated a list of URLs via Generate list, give each URL to a separate worker.

A Node.js example:

javascript Copy

const puppeteer = require('puppeteer-core');

const CDP_URLS = [
  'ws://...',
  'ws://...',
  'ws://...',
];

async function runJob(cdpUrl, targetUrl) {
  const browser = await puppeteer.connect({ browserWSEndpoint: cdpUrl });

  try {
    const page = await browser.newPage();
    await page.goto(targetUrl, { timeout: 120000 });
    return await page.title();
  } finally {
    await browser.close();
  }
}

(async () => {
  const results = await Promise.all(
    CDP_URLS.map((url, index) => runJob(url, `https://example.com/?job=${index}`))
  );

  console.log(results);
})();

Troubleshooting

Can't connect to the browser

Check that:

the CDP URL was copied in full;
the URL begins with ws://;
the host is cb.2captcha.com;
the port is 9222;
you have browser traffic available;
your network isn't blocking WebSocket connections;
in Playwright you're using connect_over_cdp;
in Puppeteer you're using puppeteer.connect, not puppeteer.launch.

Authorization error

Copy the CDP URL again from the Dashboard.

Don't use an old URL if any of these have changed:

country;
proxy mode;
proxy account;
custom proxy;
profile ID;
service password.

Custom proxy doesn't work

Check that:

the protocol is selected correctly;
the host is specified without http:// and without a port;
the port is specified separately;
login and password are filled in only if the proxy requires authentication;
the proxy is reachable from the outside;
the proxy supports the selected protocol;
after changing the form, the CDP URL was copied again.

Country didn't apply

Change Country and copy a new CDP URL.

If you're using Generate list, click Generate again after changing the country.

Page takes a long time to load

Set a timeout of 120 seconds or more.

Also open Live to see what's happening in the browser: a load in progress, a redirect, a CAPTCHA, a site error, or waiting for a resource.

Traffic runs out quickly

Check whether your scenario is loading too many images, videos, fonts, or unnecessary pages.

To save traffic, you can block heavy resources.

Example for Puppeteer:

javascript Copy

await page.setRequestInterception(true);

page.on('request', request => {
  const type = request.resourceType();

  if (['image', 'media', 'font'].includes(type)) {
    request.abort();
  } else {
    request.continue();
  }
});

Element not found

Possible reasons:

the page hasn't finished rendering yet;
you need a different selector;
the element appears after a click or scroll;
the site showed a CAPTCHA or redirect;
the target URL opened a different regional version of the page.

Open Live and check the actual state of the page.

FAQs

Do I need to install Chrome on my server?

No. The browser runs in the 2Captcha cloud. On your side, all you need is your code and an automation library.

Can I use Playwright?

Yes. Use chromium.connect_over_cdp(CDP_URL).

Can I use Puppeteer?

Yes. Use puppeteer.connect({ browserWSEndpoint: CDP_URL }).

Can I reuse the same CDP URL many times?

For independent parallel tasks, it's better to generate a separate CDP URL for each session. Use Generate list for this.

What's the difference between Custom proxy and Proxy account?

Custom proxy is an external proxy you enter manually.

Proxy account is a proxy from your 2Captcha dashboard that you pick from a list and that fills in automatically.

Yes. In Custom proxy mode, leave Login and Password empty. The proxy URL will then be built in the format:

text Copy

{protocol}://{host}:{port}

What does Country do?

Country sets the country of the browser session. In Proxy account mode, the same country is used for the proxy session.

What does Refresh do?

Refresh creates a new profile ID and updates a single CDP URL.

What does Generate list do?

Generate list creates multiple CDP URLs. Each URL is intended for a separate browser session.

What is a profile ID?

A profile ID is the identifier of a browser session. It's created automatically and is part of the CDP URL.

Example:

text Copy

profilea3f9k

Open the Browser API Dashboard.
Check browser traffic.
Select Country.
Choose Custom proxy or Proxy account.
Copy the CDP URL with Copy.
Connect via Playwright or Puppeteer.
Set a timeout of 120 seconds.
Wait for the element you need or get the HTML.
Close the browser with browser.close().
If something fails, open Live.

UI Update (Cloud Browser Dashboard)

Browser Logins

A Browser Login is the main entity of Cloud Browser.

For each login, the following is shown:

CDP URL;
Created At;
Duration;
Traffic;
Active Profiles;
Live;
Generate Profiles;
Flush Profiles.

The current login limit is shown at the top of the table:

Copy

Logins 3/10

The + Add button opens a window for creating a new login.

Active Profiles

Shows the number of active profiles and the maximum limit.

Example:

Copy

23/1000

Flush Profiles

Deletes all profiles of the selected login.

A confirmation is shown before deletion:

Copy

All profile data will be permanently deleted.
Are you sure?

Proxy Information

For service proxies, the following is shown:

Copy

account_id + proxy URL

For custom proxies:

Copy

login + proxy URL

The "No proxy attached" option is no longer used.

To create a login, click + Add.

Visible name

The display name of the login.

Password

By default, the password is generated automatically.

To set your own password:

Enable Set custom password.
Enter your password.

The following options are supported:

2Captcha account

account selection;
region selection.

Custom

protocol;
host;
port;
login;
password.

Generate Profile URLs

The Generate Profiles button opens the profile generation window.

Count

The number of URLs to generate.

The maximum is calculated automatically:

Copy

1000 - Active Profiles

Example:

Copy

max 977 (1000 - 23 active)

For each profile, the following is shown:

Profile ID;
creation date;
last activity;
traffic usage;
status.

Browser API

Browser-Fingerabdrücke

Unlocker APIDemnächst

Software

Blog

Anleitungen

Captcha-Demos