What is Browser API

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

Typical workflow:

• You open the Browser API Dashboard.
• Choose the country and proxy mode.
• Copy the ready-made CDP URL.
• Paste it into Playwright or Puppeteer.
• The script opens the site, performs actions, and gets the result.

When to use Browser API

Browser API is the right choice when a plain HTTP request isn't enough.

Use it if the site:

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

What you get

With Browser API you can:

• run remote browser sessions;
• connect to them via Playwright, Puppeteer, and CDP clients;
• choose the session's country;
• use your own external proxy or a 2Captcha proxy account;
• generate a single CDP URL or a list of URLs for parallel work;
• view active sessions via Live;
• solve CAPTCHA within the browser scenario;
• track browser traffic usage.

Public API and the Captcha CDP Interface

Documentation for users of the public 2Captcha Browser API and the CDP interface for controlling CAPTCHA solving inside the cloud browser.

Browser API lets you create and manage browser logins, browser profiles, proxy settings, limits, and traffic statistics, and get a ready-made WebSocket URL to connect to the cloud browser via the Chrome DevTools Protocol (CDP).

The Captcha CDP interface is available inside a connected browser session and lets you enable CAPTCHA auto-solving, trigger solving manually, and track solve events.

1. Basics

Base URL

https://api.2captcha.com

Authorization

All requests use a regular 2Captcha API key. The same key is used for CAPTCHA recognition, the Fingerprint API, the Proxy API, and the Browser API.

You can pass the key parameter in requests:

key=YOUR_API_KEY

For compatibility, clientKey is also supported:

clientKey=YOUR_API_KEY

Request format

GET methods accept parameters in the query string.

POST, PUT, and DELETE methods accept a JSON body and require the header:

Content-Type: application/json

Successful response format

Successful responses contain:

{
  "status": "OK"
}

Additional data is returned in response fields: account, profiles, connectionUri, browserTraffic, statistics, and others, depending on the method.

Error format

{
  "errorCode": "ERROR_PROXY_REQUIRED",
  "error": "Proxy is required"
}

2. Quick Start

Step 1. Create a browser login

A browser login can be created without a saved proxy, and the proxy can be passed later when getting connectionUri.

curl -X POST "https://api.2captcha.com/browser/accounts" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "YOUR_API_KEY",
    "name": "My browser login",
    "proxyMode": "none"
  }'

Example response:

{
  "status": "OK",
  "account": {
    "id": 58,
    "login": "bc15b7f53510063b2593",
    "password": "browserPassword",
    "name": "My browser login",
    "proxyMode": "none",
    "connectionUri": "ws://bc15b7f53510063b2593-zone-scraping_browser-country-us-pid-p0123456789abcdef0123456789abcdef:browserPassword@cb.2captcha.com:9222"
  }
}

Save account.id. You'll need it to get connectionUri and to manage profiles.

Creating a browser login also automatically creates a Default profile. Its profileId is generated randomly and looks like p<random>, for example p0123456789abcdef0123456789abcdef. Don't construct the Default profile's ID from account.id yourself.

Step 2. Get the WebSocket URL to connect

curl -X POST "https://api.2captcha.com/browser/connection" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "YOUR_API_KEY",
    "accountId": 58,
    "customProxy": {
      "type": "http",
      "host": "1.1.1.1",
      "port": 8080,
      "login": "proxyuser",
      "password": "proxypass"
    }
  }'

Example response:

{
  "status": "OK",
  "connectionUri": "ws://bc15b7f53510063b2593-zone-scraping_browser-country-us-pid-p0123456789abcdef0123456789abcdef-proxy-aHR0cDovL3Byb3h5dXNlcjpwcm94eXBhc3NAMS4xLjEuMTo4MDgw:browserPassword@cb.2captcha.com:9222"
}

The /browser/connection method returns the ready-made URL and, if a new profileId is specified, immediately creates a profile record. The browser session itself isn't started yet: it begins once a client connects to the WebSocket URL.

Step 3. Connect via Playwright

import { chromium } from 'playwright';

const browser = await chromium.connectOverCDP(connectionUri);
const context = browser.contexts()[0];
const page = await context.newPage();

await page.goto('https://example.com');

Step 4. Connect via Puppeteer

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: connectionUri
});

const page = await browser.newPage();
await page.goto('https://example.com');

3. Proxy

Working without a saved proxy

At the moment, a browser login can be created with proxyMode: "none". Its Default profile is also created without a saved proxy and works through a free IPv6 proxy. A separately created profile with proxyMode: "none" works the same way.

Important: the IPv6 mode without an explicitly set proxy is temporary and will be disabled. For stable integration, configure a 2Captcha proxy, a saved customProxy, or pass a proxy in the connection string in advance.

After the IPv6 fallback is disabled, if no proxy is found when connecting, browser authorization will return an error:

{
  "errorCode": "ERROR_PROXY_REQUIRED",
  "error": "Proxy is required"
}

proxyMode: "none" means that the browser login or profile has no saved proxy. While the IPv6 fallback is available, such a profile can work without another proxy. Once it's disabled, a proxy will need to be passed some other way.

Proxy modes for browser logins

Proxy modes for profiles

Profiles support the same modes as browser logins, plus an inheritance mode:

Proxy selection priority

When authorizing the browser, a proxy is selected in this order:

1. A custom proxy passed directly when getting connectionUri, or embedded in the WebSocket URL.
2. Proxy settings saved on the profile.
3. Proxy settings saved on the browser login.

If no proxy is found after checking all levels, the temporary IPv6 fallback is currently used. After it's disabled, the connection will be rejected with the ERROR_PROXY_REQUIRED error.

The customProxy object

{
  "type": "http",
  "host": "1.1.1.1",
  "port": 8080,
  "login": "proxyuser",
  "password": "proxypass"
}

If the proxy doesn't require authorization, the login and password fields can be omitted.

Passing a proxy inside the WebSocket URL

A proxy can be embedded in the browser's username in base64url format.

Original proxy URL:

http://proxyuser:proxypass@1.1.1.1:8080

Base64url:

aHR0cDovL3Byb3h5dXNlcjpwcm94eXBhc3NAMS4xLjEuMTo4MDgw

Username format:

{browserLogin}-zone-scraping_browser-country-{countryCode}-pid-{profileId}-dt-{deviceType}-clickcaptcha-proxy-{encodedProxy}

The -dt-{deviceType}, -clickcaptcha (or -nocaptcha), and -proxy-{encodedProxy} segments are optional and are added to the username in this order, right after -pid-{profileId}:

• -dt-{deviceType} — browser device type. Defaults to windows; you can specify -dt-android.
• -clickcaptcha — enables solving reCAPTCHA by clicking. A value-less flag.
• -nocaptcha — disables CAPTCHA solving. A value-less flag, mutually exclusive with -clickcaptcha.
• -proxy-{encodedProxy} — passes a custom proxy directly in the connection URL. Added last, right before the password.

The deviceType, clickcaptcha, and nocaptcha parameters are currently only passed via username segments when manually assembling the WebSocket URL. The POST /browser/connection method doesn't accept these fields.

Full WebSocket URL:

ws://bc15b7f53510063b2593-zone-scraping_browser-country-us-pid-profile_1-proxy-aHR0cDovL3Byb3h5dXNlcjpwcm94eXBhc3NAMS4xLjEuMTo4MDgw:browserPassword@cb.2captcha.com:9222

Example of assembling the URL in JavaScript:

const proxy = 'http://proxyuser:proxypass@1.1.1.1:8080';
const encodedProxy = Buffer.from(proxy).toString('base64url');

const username = `${browserLogin}-zone-scraping_browser-country-${countryCode}-pid-${profileId}-proxy-${encodedProxy}`;
const connectionUri = `ws://${username}:${browserPassword}@cb.2captcha.com:9222`;

For scenarios that don't need deviceType, clickcaptcha, or nocaptcha, it's recommended to get a ready-made connectionUri via the POST /browser/connection method.

4. Browser API Account Status

GET /browser

Returns the status of the Browser API account: available and used traffic, browser login and profile limits, and proxy availability information.

GET /browser?key=YOUR_API_KEY

Example:

curl "https://api.2captcha.com/browser?key=YOUR_API_KEY"

Example response:

{
  "status": "OK",
  "browserTraffic": {
    "totalKb": 1048576,
    "usedKb": 0,
    "availableKb": 1048576,
    "totalGb": 1,
    "usedGb": 0,
    "availableGb": 1
  },
  "accounts": {
    "count": 1,
    "max": 10,
    "unlimited": false
  },
  "profiles": {
    "count": 1,
    "maxPerAccount": 1000,
    "unlimited": false
  },
  "proxy": {
    "available": true,
    "count": 1,
    "attached": false
  }
}

Exceeding the browser login limit

If the number of browser logins has reached the accounts.max value, creating a new login (POST /browser/accounts) is rejected:

{
  "errorCode": "ERROR_MAX_ACCOUNTS",
  "error": "The maximum number of browser accounts cannot exceed 10",
  "maxAccounts": 10
}

The response additionally contains the maxAccounts field — this isn't part of the general error format (see section 1), but an extension specific to this code.

Exceeding the profile limit

If the number of profiles per browser login has reached the profiles.maxPerAccount value, creating a single new profile via POST /browser/profiles or POST /browser/connection is rejected:

{
  "errorCode": "ERROR_MAX_PROFILES",
  "error": "The maximum number of profiles per browser account cannot exceed 1000",
  "maxPerAccount": 1000
}

The response additionally contains the maxPerAccount field — as with ERROR_MAX_ACCOUNTS, this is an extension specific to this code.

In the Dashboard, bulk CDP URL generation works differently: a generated profile's record is created and starts counting toward the limit only after the first actual CDP connection. This deferred activation doesn't apply to creating profiles one at a time via the public API.

5. Browser Logins

A browser login (Browser Account) is the core entity of the Browser API. It's used to create browser profiles and to form the connectionUri used for connecting. In the Dashboard, this same entity is called a browser account — these are two names for the same object.

Don't confuse the browser login as an API entity with the login field in its JSON representation.

For example:

{
  "id": 58,
  "login": "bc15b7f53510063b2593",
  "password": "browserPassword"
}

Here:

• Browser Account (browser login) — the API entity itself;
• login — the browser login used when connecting via CDP;
• password — the browser password used when connecting via CDP.

List of browser logins

GET /browser/accounts?key=YOUR_API_KEY

Example:

curl "https://api.2captcha.com/browser/accounts?key=YOUR_API_KEY"

The browser login object in the response contains a nested profile field with the current connection profile. For a new account, this is initially the Default profile, but the field can later point to a different profile. Below is an abbreviated example of a new account where the current profile is the Default profile:

{
  "id": 1581,
  "login": "bc15b7f53510063b2593",
  "password": "browserPassword",
  "name": "My browser login",
  "status": 1,
  "country": "de",
  "proxyAccountId": 2,
  "proxyMode": "our_proxy",
  "profile": {
    "id": 12300,
    "accountId": 1581,
    "profileId": "p0123456789abcdef0123456789abcdef",
    "name": "Default profile",
    "country": "de",
    "proxyAccountId": null,
    "proxyMode": "inherit",
    "connectionUri": "ws://bc15b7f53510063b2593-zone-scraping_browser-country-de-pid-p0123456789abcdef0123456789abcdef:browserPassword@cb.2captcha.com:9222"
  },
  "profilesCount": 1,
  "connectionUri": "ws://bc15b7f53510063b2593-zone-scraping_browser-country-de-pid-p0123456789abcdef0123456789abcdef:browserPassword@cb.2captcha.com:9222"
}

profile.id is the numeric internal record ID. For CDP URLs and Browser API methods, use the string field profile.profileId. The Default profile has proxyMode: "inherit", so in the example it inherits the country de from the browser login.

Create a browser login

POST /browser/accounts
Content-Type: application/json

Create a login with a saved custom proxy

curl -X POST "https://api.2captcha.com/browser/accounts" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "YOUR_API_KEY",
    "name": "My browser login",
    "proxyMode": "custom_proxy",
    "customProxy": {
      "type": "http",
      "host": "1.1.1.1",
      "port": 8080,
      "login": "proxyuser",
      "password": "proxypass"
    }
  }'

Example response:

{
  "status": "OK",
  "account": {
    "id": 58,
    "login": "bc15b7f53510063b2593",
    "password": "browserPassword",
    "name": "My browser login",
    "proxyMode": "custom_proxy",
    "customProxy": {
      "type": "http",
      "host": "1.1.1.1",
      "port": 8080,
      "login": "proxyuser",
      "password": "proxypass"
    },
    "connectionUri": "ws://bc15b7f53510063b2593-zone-scraping_browser-country-us-pid-p0123456789abcdef0123456789abcdef:browserPassword@cb.2captcha.com:9222"
  }
}

Create a login with a 2Captcha proxy account

curl -X POST "https://api.2captcha.com/browser/accounts" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "YOUR_API_KEY",
    "name": "My browser login",
    "proxyMode": "our_proxy",
    "proxyAccountId": 2,
    "country": "fr"
  }'

Example response:

{
  "status": "OK",
  "account": {
    "id": 58,
    "login": "bc15b7f53510063b2593",
    "password": "browserPassword",
    "name": "My browser login",
    "country": "fr",
    "proxyAccountId": 2,
    "proxyMode": "our_proxy",
    "proxy": {
      "id": 2,
      "login": "proxyAccountLogin",
      "password": "proxyAccountPassword",
      "type": "http",
      "host": "eu.proxy.2captcha.com",
      "port": 2334,
      "sessionTime": 120
    },
    "profile": {
      "id": 12300,
      "accountId": 58,
      "profileId": "p0123456789abcdef0123456789abcdef",
      "name": "Default profile",
      "zone": "scraping_browser",
      "country": "fr",
      "proxyMode": "inherit",
      "connectionUri": "ws://bc15b7f53510063b2593-zone-scraping_browser-country-fr-pid-p0123456789abcdef0123456789abcdef:browserPassword@cb.2captcha.com:9222"
    },
    "profilesCount": 1,
    "connectionUri": "ws://bc15b7f53510063b2593-zone-scraping_browser-country-fr-pid-p0123456789abcdef0123456789abcdef:browserPassword@cb.2captcha.com:9222"
  }
}

The country field sets the exit country for the selected 2Captcha proxy account. Pass a lowercase two-letter country code, e.g. fr for France. The parameter applies when proxyMode: "our_proxy" and is included in the username of the resulting CDP URL, in the -country-{countryCode}- segment.

For example, for "country": "fr" the CDP URL contains -country-fr-:

ws://<browser_login>-zone-scraping_browser-country-fr-pid-<profile_id>:<browser_password>@cb.2captcha.com:9222

Create a login without a saved proxy

{
  "key": "YOUR_API_KEY",
  "name": "My browser login",
  "proxyMode": "none"
}

Example response:

{
  "status": "OK",
  "account": {
    "id": 58,
    "login": "bc15b7f53510063b2593",
    "password": "browserPassword",
    "name": "My browser login",
    "proxyMode": "none",
    "connectionUri": "ws://bc15b7f53510063b2593-zone-scraping_browser-country-us-pid-p0123456789abcdef0123456789abcdef:browserPassword@cb.2captcha.com:9222"
  }
}

While the temporary IPv6 fallback is available (see section 3), the connectionUri from this response works even without an explicitly set proxy.

Update a browser login

PUT /browser/accounts
Content-Type: application/json

Example:

curl -X PUT "https://api.2captcha.com/browser/accounts" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "YOUR_API_KEY",
    "id": 58,
    "name": "Updated login",
    "proxyMode": "our_proxy",
    "proxyAccountId": 2,
    "country": "fr"
  }'

The country field can be passed to change the exit country. If country isn't passed on update, the current country is kept. This rule also applies when changing proxyAccountId: the proxy account changes, but the previously selected country stays the same.

Regenerate a browser login's password

{
  "key": "YOUR_API_KEY",
  "id": 58,
  "regeneratePassword": true
}

After regeneration, old WebSocket URLs with the previous password will no longer work for new connections.

Delete a browser login

DELETE /browser/accounts
Content-Type: application/json

Example:

curl -X DELETE "https://api.2captcha.com/browser/accounts" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "YOUR_API_KEY",
    "id": 58
  }'

6. Browser Profiles

A browser profile stores the settings of a specific browser environment within a browser login. One browser login can have multiple profiles.

Profile limits

• A profile supports only one active CDP connection at a time. Trying to connect to an already-occupied profile (for example, opening a second connectionUri for the same profile while the first one is still in use) is rejected with a profile_locked error. Wait for the current session to finish, or use a different profile.
• A profile can be updated while a CDP connection is active. The current session will keep running with its previous settings until the connection ends.
• Maximum duration of a single browser session — 30 minutes.
• Profiles are stored for 90 days from creation, or until deleted by the user.
• In the web interface, the Default profile can be deleted if the browser login has another profile. The only or last remaining profile cannot be deleted. This restriction applies to the Dashboard; the behavior of DELETE /browser/profiles is described separately below.

List of profiles

GET /browser/profiles?key=YOUR_API_KEY&accountId=58&page=1&limit=50

Example:

curl "https://api.2captcha.com/browser/profiles?key=YOUR_API_KEY&accountId=58&page=1&limit=50"

Parameters:

Create or update a profile

POST /browser/profiles
Content-Type: application/json

Example of a profile that inherits the proxy from the browser login:

curl -X POST "https://api.2captcha.com/browser/profiles" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "YOUR_API_KEY",
    "accountId": 58,
    "profileId": "profile_1",
    "name": "Profile 1",
    "proxyMode": "inherit"
  }'

When creating or updating a profile with proxyMode: "inherit", the parent browser login's proxy settings and country apply. When switching from another mode to inherit:

• the profile's own proxy settings are reset;
• proxyAccountId, proxy, and customProxy on the profile object are null, since the effective settings come from the account;
• the profile's country field takes the account's country;
• profileId, name, accumulated statistics, and creation date are preserved.

Example of a profile with separate 2Captcha proxy settings:

{
  "key": "YOUR_API_KEY",
  "accountId": 58,
  "profileId": "profile_1",
  "name": "Profile 1",
  "proxyMode": "our_proxy",
  "proxyAccountId": 2,
  "country": "fr"
}

With proxyMode: "our_proxy", the country field sets the exit country for the profile. If country is passed, the profile is created with the specified country. If country isn't passed, the profile inherits the country from the parent browser login's settings.

When creating a profile, or switching from another mode to our_proxy, the proxyAccountId field is required. If you pass only proxyMode: "our_proxy" without proxyAccountId, the API returns an error:

{
  "errorCode": "ERROR_PROXY_ACCOUNT_ID",
  "error": "proxyAccountId is required for our_proxy mode"
}

On a correct transition from none to our_proxy with the proxyAccountId field:

• the existing profile is updated without changing profileId;
• proxyMode changes to our_proxy;
• proxyAccountId and the proxy object are populated with the selected 2Captcha proxy account's data;
• customProxy stays null;
• if country isn't passed, the profile's previous country is kept;
• name, accumulated statistics, and creation date are preserved.

If you pass the same accountId and an existing profileId, the method updates the profile instead of creating a new one. When switching proxyMode from inherit to none:

• profileId, name, accumulated statistics, and creation date are preserved;
• proxyAccountId is reset to null;
• proxy and customProxy are reset to null;
• the saved country value doesn't change.

In the Dashboard, a profile with proxyMode: "none" shows a warning: pass a proxy in the connection URL, otherwise a free IPv6 proxy will currently be used. This fallback will be disabled.

Example of a profile with a separate saved custom proxy:

{
  "key": "YOUR_API_KEY",
  "accountId": 58,
  "profileId": "profile_1",
  "name": "Profile 1",
  "proxyMode": "custom_proxy",
  "customProxy": {
    "type": "socks5",
    "host": "proxy.example.com",
    "port": 1080,
    "login": "proxyuser",
    "password": "proxypass"
  }
}

When creating a profile, or switching from another mode to custom_proxy, the customProxy object is required. If you pass proxyMode: "custom_proxy" without customProxy data, the API returns an error:

{
  "errorCode": "ERROR_CUSTOM_PROXY",
  "error": "customProxy is required for custom_proxy mode"
}

On a correct transition to custom_proxy:

• the existing profile is updated without changing profileId;
• proxyMode changes to custom_proxy;
• proxyAccountId is reset to null;
• the proxy object is reset to null;
• the passed data is saved into customProxy;
• the profile's previous country, name, statistics, and creation date are preserved.

With proxyMode: "custom_proxy", the actual exit country is determined by the external proxy itself. The saved country field, the country shown on the profile card, and the -country-{countryCode}- segment in the CDP URL don't override customProxy's geography and may not match the real exit country.

Delete a profile

DELETE /browser/profiles
Content-Type: application/json

Delete a single profile:

{
  "key": "YOUR_API_KEY",
  "accountId": 58,
  "profileId": "profile_1"
}

Delete all profiles of a browser login and recreate a Default profile:

{
  "key": "YOUR_API_KEY",
  "accountId": 58,
  "deleteAll": true
}

A browser login can't be left without a profile. When the last profile is deleted programmatically, the API resets its data and creates a new Default profile with a new random profileId.

This rule applies in both cases:

• if the last profile was a custom one, it's replaced by a new Default profile;
• if the account only had a Default profile, it's reset and replaced by a new Default profile.

In both cases, the old profileId is no longer usable. Get the new profileId from the updated browser login data.

7. 2Captcha Proxy Accounts

Browser API can use 2Captcha proxy accounts purchased or connected by the user.

List of proxy accounts

GET /browser/proxy_accounts?key=YOUR_API_KEY

Example:

curl "https://api.2captcha.com/browser/proxy_accounts?key=YOUR_API_KEY"

Example response:

{
  "status": "OK",
  "proxy": {
    "available": true,
    "data": [
      {
        "id": 2,
        "login": "u895ed2e43b5c04bf",
        "password": "qwerty123456",
        "type": "http",
        "zone": "custom",
        "host": "eu.proxy.2captcha.com",
        "port": 2334,
        "sessionTime": 120,
        "status": 1
      }
    ]
  }
}

Use the id from the response as proxyAccountId in the browser login or profile settings.

8. Getting connectionUri

POST /browser/connection

The method returns a ready-made WebSocket URL for a browser login or profile. If a new profileId is passed in the request, the profile is created in the database right away and counts toward the profile limit.

POST /browser/connection
Content-Type: application/json

Use the saved proxy settings:

{
  "key": "YOUR_API_KEY",
  "accountId": 58,
  "profileId": "profile_1"
}

The profileId parameter can be omitted:

{
  "key": "YOUR_API_KEY",
  "accountId": 58
}

In this case, the method uses the profile from the current account.profile field. This isn't necessarily the Default profile: if account.profile points to a different profile, that profile's profileId will be included in connectionUri. In the response, the selected profile is also returned in the top-level profile field.

Use a custom proxy just for this connection:

{
  "key": "YOUR_API_KEY",
  "accountId": 58,
  "profileId": "profile_1",
  "customProxy": {
    "type": "http",
    "host": "1.1.1.1",
    "port": 8080,
    "login": "proxyuser",
    "password": "proxypass"
  }
}

Example response:

{
  "status": "OK",
  "connectionUri": "ws://bc15b7f53510063b2593-zone-scraping_browser-country-us-pid-profile_1-proxy-aHR0cDovL3Byb3h5dXNlcjpwcm94eXBhc3NAMS4xLjEuMTo4MDgw:browserPassword@cb.2captcha.com:9222"
}

Important: creating the profile record doesn't start a browser session. The session begins once Playwright, Puppeteer, or another CDP client connects to connectionUri.

9. Traffic History and Statistics

Traffic operation history

GET /browser/history?key=YOUR_API_KEY&limit=50

Example:

curl "https://api.2captcha.com/browser/history?key=YOUR_API_KEY&limit=50"

Traffic statistics

GET /browser/statistics?key=YOUR_API_KEY&dateFrom=2026-07-01&dateTo=2026-07-31

Optional filters:

Example:

curl "https://api.2captcha.com/browser/statistics?key=YOUR_API_KEY&accountId=58&dateFrom=2026-07-01&dateTo=2026-07-31"

10. Common Browser API Error Codes

Captcha CDP Interface

11. Purpose

The Captcha CDP domain lets you control CAPTCHA solving on the cloud browser's current tab.

Two modes are available:

1. Auto-solve after the page loads.
2. Manual solve trigger via the Captcha.solve command.

CDP events let you track progress: CAPTCHA detection, sending the request to the service, successful solving, or an error.

12. Connecting to a CDP Session

Playwright

import { chromium } from 'playwright';

const browser = await chromium.connectOverCDP(connectionUri);
const context = browser.contexts()[0];
const page = await context.newPage();
const session = await context.newCDPSession(page);

Puppeteer

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: connectionUri
});

const page = await browser.newPage();
const session = await page.target().createCDPSession();

13. CDP Data Types

CaptchaOptions

One element of the options array. Usually a single object is passed.

{
  "type": "*",
  "submitForm": false,
  "selector": ".captcha-container",
  "detectSelector": ".captcha-container",
  "responseSelector": "textarea[name=\"g-recaptcha-response\"]"
}

SolveResult

The response of the Captcha.solve command, returned in the result field.

{
  "result": {
    "status": "solveFinished",
    "token": "03AGdBq26..."
  }
}

14. CDP Commands

Captcha.setAutoSolve

Enables or disables automatic CAPTCHA solving on the tab.

await session.send('Captcha.setAutoSolve', {
  autoSolve: true,
  options: [
    {
      type: '*'
    }
  ]
});

Parameters:

Response: no body on success.

Possible CDP error:

No active frame

Captcha.solve

Triggers explicit CAPTCHA solving on the current tab.

const response = await session.send('Captcha.solve', {
  detectTimeout: 15000,
  options: [
    {
      type: '*'
    }
  ]
});

console.log(response.result.status);
console.log(response.result.token);

Parameters:

Example successful response:

{
  "result": {
    "status": "solveFinished",
    "token": "03AGdBq26..."
  }
}

Example result if the CAPTCHA isn't found:

{
  "result": {
    "status": "notDetected"
  }
}

Possible CDP errors without a SolveResult:

No active frame
Captcha.solve timed out waiting for extension response

15. CDP Events

Subscribing in Playwright:

session.on('Captcha.detected', () => {
  console.log('CAPTCHA detected');
});

session.on('Captcha.waitForSolve', () => {
  console.log('CAPTCHA sent to solver');
});

session.on('Captcha.solveFinished', () => {
  console.log('CAPTCHA solved');
});

session.on('Captcha.solveFailed', () => {
  console.log('CAPTCHA solve failed');
});

Events:

Event chain in auto mode:

Captcha.detected → Captcha.waitForSolve → Captcha.solveFinished | Captcha.solveFailed

Events are for tracking progress. The token is only returned in the response of the Captcha.solve command.

16. Recommended CDP Scenarios

Auto-solving CAPTCHA

Use auto-solve if you need the browser to solve CAPTCHA on its own after the page loads.

await session.send('Captcha.setAutoSolve', {
  autoSolve: true,
  options: [{ type: '*' }]
});

const solved = new Promise((resolve, reject) => {
  session.once('Captcha.solveFinished', resolve);
  session.once('Captcha.solveFailed', reject);
});

await page.goto('https://example.com');
await solved;

Recommended order:

Captcha.setAutoSolve({ autoSolve: true, options })
  → navigate to the page with the CAPTCHA
  → wait for the Captcha.solveFinished or Captcha.solveFailed event

In auto mode, you don't need to retrieve and apply the token yourself: it's written to the page automatically, and the form is submitted automatically if needed (see responseSelector and submitForm in CaptchaOptions, section 13). The events only let you track when solving is done; the token itself isn't passed in any event.

Manual Solve Trigger

Use the manual trigger if you need to control when solving starts and get the token in the command's response.

await session.send('Captcha.setAutoSolve', {
  autoSolve: false,
  options: [{ type: '*' }]
});

await page.goto('https://example.com');
await page.waitForTimeout(5000);

const { result } = await session.send('Captcha.solve', {
  detectTimeout: 15000,
  options: [{ type: '*' }]
});

if (result.status === 'solveFinished') {
  console.log('Token:', result.token);
} else {
  console.log('Captcha solve status:', result.status, result.errorMessage);
}

Recommended order:

Captcha.setAutoSolve({ autoSolve: false, options })
  → navigation
  → 3–5 second pause, so the widget has time to register
  → Captcha.solve({ detectTimeout, options })
  → check result.status

Don't call Captcha.solve from the Captcha.detected handler. The detected event means the widget has already been found; for manual mode, a single Captcha.solve call after a short pause is enough.

17. CDP Timeouts

If your CDP client has its own timeout for the session.send command, increase it for Captcha.solve — otherwise the client may abort the wait before the service returns a result.

18. Full Example: Browser API + Playwright + CAPTCHA Auto-Solve

import { chromium } from 'playwright';

const API_KEY = 'YOUR_API_KEY';

async function createConnectionUri() {
  const response = await fetch('https://api.2captcha.com/browser/connection', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      key: API_KEY,
      accountId: 58,
      profileId: 'profile_1',
      customProxy: {
        type: 'http',
        host: '1.1.1.1',
        port: 8080,
        login: 'proxyuser',
        password: 'proxypass'
      }
    })
  });

  const data = await response.json();

  if (data.status !== 'OK') {
    throw new Error(`${data.errorCode}: ${data.error}`);
  }

  return data.connectionUri;
}

const connectionUri = await createConnectionUri();

const browser = await chromium.connectOverCDP(connectionUri);
const context = browser.contexts()[0];
const page = await context.newPage();
const session = await context.newCDPSession(page);

session.on('Captcha.detected', () => console.log('CAPTCHA detected'));
session.on('Captcha.waitForSolve', () => console.log('Waiting for 2Captcha'));
session.on('Captcha.solveFinished', () => console.log('CAPTCHA solved'));
session.on('Captcha.solveFailed', () => console.log('CAPTCHA solve failed'));

await session.send('Captcha.setAutoSolve', {
  autoSolve: true,
  options: [{ type: '*' }]
});

await page.goto('https://example.com');

19. Full Example: Browser API + Playwright + Manual Captcha.solve

import { chromium } from 'playwright';

const connectionUri = 'ws://...';

const browser = await chromium.connectOverCDP(connectionUri);
const context = browser.contexts()[0];
const page = await context.newPage();
const session = await context.newCDPSession(page);

await session.send('Captcha.setAutoSolve', {
  autoSolve: false,
  options: [{ type: '*' }]
});

await page.goto('https://example.com');
await page.waitForTimeout(5000);

const { result } = await session.send('Captcha.solve', {
  detectTimeout: 15000,
  options: [{ type: '*' }]
});

switch (result.status) {
  case 'solveFinished':
    console.log('CAPTCHA token:', result.token);
    break;

  case 'solveFailed':
    console.log('CAPTCHA solve failed:', result.errorMessage);
    break;

  case 'notDetected':
    console.log('CAPTCHA was not detected on the page');
    break;

  case 'invalid':
    console.log('Invalid solve request:', result.errorMessage);
    break;

  default:
    console.log('Unknown CAPTCHA status:', result.status);
}

20. Integration Recommendations

1. Get connectionUri via POST /browser/connection rather than assembling the WebSocket URL by hand, unless you have a specific reason to.
2. Always pass a working proxy: via customProxy, profile settings, browser login settings, or a 2Captcha proxy account.
3. For reliable isolation, use separate profiles for different scenarios.
4. For scenarios where you only need the fact that the CAPTCHA was passed successfully, use auto-solve and events.
5. For scenarios where you need the token, use manual Captcha.solve.
6. Increase the CDP client timeout for manual CAPTCHA solving.
7. Check result.status, not just whether the CDP command returned a response.
8. Log the Captcha.detected, Captcha.waitForSolve, Captcha.solveFinished, and Captcha.solveFailed events for diagnostics.

Working through the Dashboard

This part describes working with Browser API through the 2Captcha Dashboard: creating browser accounts and profiles, setting up proxies, getting a CDP URL, and watching sessions via Live.

1. Core logic

Browser API has two main entities: a browser account and a browser profile.

A browser account stores shared settings: login, password, proxy, country, and total traffic usage across all profiles of that account.

A browser profile is a separate browser session within an account. Each profile has its own CDP URL, status, traffic usage, request count, and Live link.

The simplest way to think about it:

Browser account = shared settings and credentials
Browser profile = a specific session to run
CDP URL = the connection address to the profile from Playwright / Puppeteer
Live = visual view of a specific profile

The typical process looks like this:

1. Create a browser account
2. Choose how it will work with a proxy
3. Use the Default profile or create additional profiles
4. Copy the CDP URL of the desired profile
5. Connect from your code or open Live

2. Browser API sections

Browser API has several main tabs.

Browser Accounts

This is where browser accounts are created, and cards of already-created accounts are displayed.

On this tab you can:

• create a browser account;
• choose a proxy for the account;
• create an account without a proxy to set it up later;
• view the account's login and password;
• copy the CDP URL of the selected profile;
• open Live;
• create additional profiles;
• go to active profiles;
• change proxy settings or country;
• delete profiles or the account.

Browser Profiles

This is where browser profiles are displayed.

You can view:

• the overall list of profiles;
• the list of profiles for the selected browser account.

On this tab you can work with specific profiles: check status, copy the CDP URL, open Live, check traffic, and delete profiles.

Connection Setup

Here you can choose connection parameters and get a code sample.

Sample code is available for:

• Puppeteer;
• Playwright Node.js;
• Playwright Python;
• Playwright Java;
• Playwright .NET.

Documentation

The section describing Browser API.

Proxy

The section for managing proxies and traffic.

2.1. Demo account for a first look

To get a first look at Browser API, you don't need to immediately create your own browser account and set up a proxy. At the start, the Browser Accounts section has a demo browser account named Default browser account, with a Default profile.

You can use this account to quickly see how a CDP connection works and what a browser session looks like in Live.

To try the demo account:

1. Open the Browser API → Browser Accounts section.
2. Find the demo account in the list of accounts.
3. In the CDP URL block, select the Default profile.
4. Click Live.
5. Make sure the remote browser session opens.

The demo account works through a free IPv6 proxy without any additional setup. This is enough for a first look at the Live view and the general logic of CDP connections, but IPv6 has limitations.

Some sites may:

• not support IPv6;
• load unreliably;
• show a connection error;
• block IPv6 traffic;
• fail to load some resources;
• behave differently than through a regular IPv4 proxy.

If a site doesn't open through the demo account, this doesn't necessarily mean there's a problem with Browser API. The specific site may simply not work with IPv6 or may restrict this type of connection.

For full-fledged work with the sites you need, create your own browser account and set up a suitable proxy for it:

• 2Captcha Proxy — if you want to use a 2Captcha proxy account and choose the connection country;
• Custom Proxy — if you want to connect an external HTTP, HTTPS, or SOCKS5 proxy;
• No proxy on the account — if you plan to pass the proxy later when creating a profile or in the connection URL.

The demo account is recommended only for an initial check of the interface, the Live view, and understanding how a browser session works.

3. Creating a browser account

A browser account is created on the Browser Accounts tab.

On the left is the Create Account form. On the right is the list of already-created accounts.

When creating an account, you need to choose a proxy option:

1. 2Captcha Proxy
2. Custom Proxy
3. No Proxy

After the account is created, its card with basic information appears on the right.

4. Creating an account with a 2Captcha proxy

This option is used when you need to work through a 2Captcha proxy.

Before creating the account, make sure proxy traffic is paid for and available.

Steps:

1. Open the Browser Accounts tab.
2. In the Create Account form, enter the account name.
3. Leave automatic password generation on, or enable Set custom password.
4. In the proxy mode, select 2Captcha Proxy.
5. In the Proxy Account field, select the proxy account you need.
6. Choose the country.
7. Click Create.

After creation, the browser account will be configured for the selected proxy account and country.

The account card will display browser and proxy information: login, password, traffic used, proxy account, geography, the CDP URL of the selected profile, and the Live link.

If the account uses a 2Captcha proxy, you can change the account's country.

5. Creating an account with a custom proxy

This option is used when you need to connect an external proxy.

Steps:

1. Open the Browser Accounts tab.
2. Enter the account name.
3. Leave automatic password generation on, or set your own password.
4. In the proxy mode, select Custom Proxy.
5. Fill in the proxy fields:
   • protocol;
   • host;
   • port;
   • login;
   • password.
6. Click Create.

After creation, the account will appear on the right in the list of accounts.

The proxy block on the account card will show the custom proxy.

Examples of proxies with authentication:

HTTP
http://login:password@proxy.example.com:3128

SOCKS5
socks5://login:password@proxy.example.com:1080

If the proxy doesn't require authentication, you can leave the login and password blank, provided this option is supported by the settings.

6. Creating an account without a proxy

You can create an account without a proxy if you plan to add one later.

Steps:

1. Open the Browser Accounts tab.
2. Enter the account name.
3. Leave automatic password generation on, or set your own password.
4. Select the no-proxy option.
5. Click Create.

Such an account can be used as a template.

A proxy can be added later:

• by changing the account settings;
• by creating a profile with separate proxy settings;
• via the CDP URL, if the proxy is passed in the connection URL.

For more on passing a custom proxy via the CDP URL, see section 13.

If proxy inheritance is disabled for a profile and no other proxy is set, the interface shows a warning. Currently, a free IPv6 proxy is used when no proxy is passed in the URL, but this fallback will be disabled. Configure a proxy in advance or pass one in the connection URL.

7. Browser account card

After the account is created, its card is displayed on the right on the Browser Accounts tab.

The account card contains basic browser information:

• account name;
• login;
• password;
• total traffic used across all profiles of the account;
• proxy settings;
• the CDP URL of the selected profile;
• the CDP URL copy button;
• the Live link;
• profile selector for connecting;
• the number of activated profiles (profiles created via CDP URL generation start counting after the first connection);
• the Create Profiles button;
• the Active Profiles link;
• the Delete Profiles button;
• the edit and delete account buttons.

From the account card you can:

Copy the CDP URL of the selected profile
Open Live for the selected profile
Change proxy settings
Change the country, if a 2Captcha proxy is used
Create additional profiles
Go to active profiles
Delete all profiles of the account
Delete the account

8. Default profile

When a browser account is created, a Default profile is automatically created.

It's there so that right after creating the account you can:

• copy the CDP URL;
• open Live;
• connect to the browser from your code.

When additional profiles are created, they appear in the profile selector on the account card. After that, you can select the profile you need and open Live specifically for it.

In the web interface, the Default profile can be deleted if the account has another profile. The account's only or last remaining profile cannot be deleted.

9. Active profiles

The account card has an Active Profiles link.

It opens the Browser Profiles tab and shows the profiles of the selected account.

This section shows only activated profiles. If a list of CDP URLs was generated through bulk profile generation, such profiles will appear here only after the first successful connection.

You can also go to the Browser Profiles tab via the top menu.

The display logic is as follows:

Account selected on the left → profiles of that account are shown on the right
No account selected → the overall list of profiles is shown on the right

10. Creating profiles from the account card

Additional profiles are needed when you require several separate browser sessions.

For example:

• for parallel runs;
• for different workers;
• for different tasks;
• for different countries;
• for different proxies;
• to isolate sessions from each other.

To create profiles:

1. Open the Browser Accounts tab.
2. Find the account you need.
3. Click Create Profiles.
4. Specify the number of profiles.
5. If needed, override the proxy for the profiles being generated. By default they inherit the account's proxy settings; if needed, you can set a different mode:
   • 2Captcha Proxy — select the proxy account and country;
   • Custom Proxy — fill in the proxy parameters.
6. Generate the list of CDP URLs.
7. Copy the result.
8. Pass the CDP URLs into your code or save them somewhere.

Important: copy the generated URLs right away. After the generation window is closed, profiles that were not activated by a connection are not saved and do not end up in the database. Such profiles are not counted toward the profile limit.

A profile is considered activated after the first connection via its CDP URL. Only then is it created in the database, starts showing up in the "Active Profiles" section, and is counted in the profile counter.

The simple rule:

Generate the URL → copy it immediately → use it or save it.

11. Browser profile card

On the Browser Profiles tab, each profile is displayed as a separate card in the list. If no browser account is selected on the left, the overall list of all profiles is shown; if an account is selected, the list is filtered to show only the profiles of that account.

The profile card contains the profile's basic information:

• status;
• number of requests;
• traffic used;
• creation date;
• proxy information;
• CDP URL;
• the CDP URL copy button;
• the Live link;
• deleting a specific profile.

You can also delete all profiles belonging to the selected browser account if you need to clear the list. The delete button is shown only when a browser account is selected.

The profile card is used when you need to work with a specific session rather than the whole account.

12. Creating a profile from the "Browser Profiles" tab

A new profile can be created for the selected browser account.

When creating a profile, you need to choose the proxy settings.

Available options:

1. Inherit settings from the browser account
2. Use a 2Captcha proxy
3. Use a custom proxy
4. No proxy, with inheritance disabled

When a profile is created from this tab, it is created immediately and saved to the database right away, so it immediately appears in the profile list and counts toward the profile limit.

By comparison: when generating a list of profiles via the Create Profiles function (Bulk Generate), only CDP URLs are created. Such a profile will get into the database, appear in the Active Profiles section, and start counting toward the limit only after the first connection via its CDP URL.

Inherit from the browser account

The profile uses the same proxy settings as the browser account.

This is a convenient option if all profiles of the account should work the same way.

2Captcha Proxy

The profile uses a 2Captcha proxy.

You need to choose:

• a proxy account;
• a country.

This option is suitable if a specific profile needs to use different settings than the browser account.

Custom Proxy

The profile uses an external proxy.

You need to fill in the fields:

• protocol;
• host;
• port;
• login;
• password.

If the proxy does not require authentication, the login and password fields can be left empty.

Such a profile will use its own proxy even if the browser account has different settings configured.

The actual exit country is determined by the external proxy itself. The country displayed on the profile card may not match the connection's actual geolocation.

No Proxy

You can disable proxy inheritance and create a profile without a proxy.

Currently, a free IPv6 proxy is used when no proxy is passed in the URL. This fallback will be disabled, so configure a proxy for stable operation. See section 6 for details.

13. CDP URL

The CDP URL is the WebSocket URL used to connect to a browser profile.

You can get the CDP URL in two places:

1. On the browser account card — for the selected profile
2. On a specific profile's card — on the "Browser Profiles" tab

The CDP URL is used in Playwright, Puppeteer, and other clients that support the Chrome DevTools Protocol.

Format example:

ws://<browser_login>-zone-scraping_browser-country-<country_code>-pid-<profile_id>:<password>@cb.2captcha.com:9222

If a proxy is passed in the connection URL, a proxy segment is also added to the CDP URL.

The CDP URL contains browser access credentials, so it must not be published anywhere public.

If a proxy is set at multiple levels at the same time, the following priority order applies:

1. Proxy passed in the connection string (CDP URL).
2. Proxy set on the profile.
3. Proxy set on the account.

Example of using a custom proxy

If the proxy is passed in the connection string, the CDP URL uses not the proxy string itself but its Base64URL representation.

For example, the proxy string:

socks5://login:password@proxy.example.com:1080

After Base64URL encoding, you get, for example:

c29ja3M1Oi8vbG9naW46cGFzc3dvcmRAcHJveHkuZXhhbXBsZS5jb206MTA4MA

Used when building the CDP URL:

ws://<browser_login>-zone-scraping_browser-country-<country_code>-pid-<profile_id>-proxy-c29ja3M1Oi8vbG9naW46cGFzc3dvcmRAcHJveHkuZXhhbXBsZS5jb206MTA4MA:<password>@cb.2captcha.com:9222

Note: in Browser API, the encoding is performed automatically when the connection string is generated in the Connection Setup section, so you usually don't need to encode the proxy string manually.

14. Live

Live opens a visual view of the browser session.

Important: Live cannot be opened for a profile that is already in use by an active CDP connection (profile_locked error, see section 20, "Limits and Storage," for details). For Live, use a free profile or wait for the existing connection to finish.

If a profile or account is deleted while a CDP connection is active, the already-open browser session will keep running until the current connection ends. In that case, reconnecting to this profile via the same CDP URL is not possible.

A profile can be updated while a CDP connection is active. The already-running session will continue using its previous settings until the current connection ends.

Live can be opened:

• from the browser account card;
• from a specific profile's card.

If the account has several profiles, first select the profile you need on the account card, then open Live.

Live is useful when you need to check:

• whether the page opened;
• what content the browser sees;
• whether a CAPTCHA appeared;
• whether a click worked;
• where a redirect went;
• why an element wasn't found;
• which proxy was applied;
• whether the browser is stuck loading.

15. Connection Setup

On the Connection Setup tab you can get a code sample for connecting.

Steps:

1. Open the Connection Setup tab.
2. Select the browser account.
3. Choose the proxy type.
4. If 2Captcha Proxy is selected, choose the proxy account and country.
5. If Custom Proxy is selected, fill in the standard fields: protocol, host, port, login, and password.
6. Choose the code sample you need.
7. Copy the code.

Samples are available for:

Puppeteer
Playwright Node.js
Playwright Python
Playwright Java
Playwright .NET

This section is convenient when you need to quickly get a connection template without manually assembling the CDP URL.

16. Quick scenario: account with a 2Captcha proxy

1. Open Browser Accounts.
2. Enter the account name.
3. Select 2Captcha Proxy.
4. Choose the proxy account.
5. Choose the country.
6. Click Create.
7. On the account card, select the Default profile.
8. Copy the CDP URL or open Live.
9. Use the CDP URL in Playwright or Puppeteer.

17. Quick scenario: account with a custom proxy

1. Open Browser Accounts.
2. Enter the account name.
3. Select Custom Proxy.
4. Fill in the protocol, host, port, login, and password.
5. Click Create.
6. On the account card, select the Default profile.
7. Copy the CDP URL or open Live.

18. Quick scenario: account without a proxy

1. Open Browser Accounts.
2. Enter the account name.
3. Select the no-proxy option.
4. Click Create.
5. Add a proxy later via the account settings, a profile, or the connection URL.

Currently, the profile uses a free IPv6 proxy when no proxy is passed in the connection URL. This fallback will be disabled.

19. Quick scenario: multiple profiles for parallel work

1. Create a browser account.
2. Make sure the proxy is configured correctly.
3. On the account card, click Create Profiles.
4. Specify the number of profiles.
5. Generate the list of CDP URLs.
6. Copy the result immediately.
7. Pass each CDP URL to a separate worker or process.
8. After the first connection, the profiles become active.
9. Active profiles can be managed on the Browser Profiles tab.

Recommendation:

One profile = one independent session
One CDP URL = one worker or one task

Reconnecting to an already-occupied profile is not possible (profile_locked error, see section 20). Use a separate profile for each parallel process.

20. Limits and storage

• Maximum duration of a single browser session — 30 minutes.
• Profiles are stored for 90 days from creation, or until deleted by the user.
• A profile supports only one active CDP connection at a time. Attempting to reconnect to an already-occupied profile (including opening Live) returns a profile_locked error. Wait for the current browser session to finish, or use a different profile.

21. Quick reference

A browser account is created with or without a proxy.
If a 2Captcha proxy is selected, you need to choose a proxy account and country.
If a custom proxy is selected, you need to fill in protocol, host, port, login, and password.
After the account is created, a Default profile automatically appears.
The CDP URL is taken from the selected profile.
A profile supports only one active connection at a time.
Live opens for a specific profile.
Additional profiles are needed for parallel runs.
Generated profile URLs must be copied immediately.
Unactivated profiles are not saved after the generation window is closed.
On the "Browser Profiles" tab you can manage profiles individually.
On the "Connection Setup" tab you can get code for Puppeteer and Playwright.

22. Minimal pre-launch checklist

Before connecting from your code, check:

Browser account created
Proxy configured
Country selected, if using a 2Captcha proxy
Profile created, or Default profile selected
CDP URL copied in full
Different profiles used for parallel tasks
Live opened to check browser state if there are issues