Browser API: User Documentation

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.

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 over IPv6 without any additional proxy setup. This is a special exception intended only for getting familiar with Browser API. Standard proxy rules, described later, apply to regular user accounts. 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/SOCKS 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.

Important: if proxy inheritance is disabled for a profile and no other proxy is set, the browser will not start without a proxy in the URL. When this option is selected, the interface shows a warning.

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.

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.

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

No Proxy

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

Important: the browser will not start without a proxy in the URL — see the warning in section 6, "Creating an account without a proxy," 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>-proxy-c29ja3M1Oi8vbG9naW46cGFzc3dvcmRAcHJveHkuZXhhbXBsZS5jb206MTA4MA-pid-<profile_id>:<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.

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.

Important: a profile without a proxy will not start unless a proxy is passed in the connection URL.

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