Что такое Browser API

Browser API запускает браузерную сессию в облаке 2Captcha. Ваш код подключается к этой сессии по WebSocket URL и управляет страницей так же, как если бы браузер был запущен локально.

Обычная схема работы:

• Вы открываете Browser API Dashboard.
• Выбираете страну и режим прокси.
• Копируете готовый CDP URL.
• Вставляете его в Playwright или Puppeteer.
• Скрипт открывает сайт, выполняет действия и получает результат.

Когда использовать Browser API

Browser API подходит, когда обычного HTTP-запроса недостаточно.

Используйте его, если сайт:

• рендерит контент через JavaScript;
• подгружает данные после загрузки страницы;
• требует кликов, ввода текста, скролла или ожидания элементов;
• показывает разные страницы в разных странах;
• использует проверки, редиректы, динамические формы или CAPTCHA;
• нестабильно работает при простом запросе через curl, requests, fetch или аналогичные инструменты.

Что вы получаете

С Browser API можно:

• запускать удаленные браузерные сессии;
• подключаться к ним через Playwright, Puppeteer и CDP-клиенты;
• выбирать страну сессии;
• использовать свой внешний прокси или proxy-аккаунт 2Captcha;
• генерировать один CDP URL или список URL для параллельной работы;
• смотреть активные сессии через Live;
• решать CAPTCHA в браузерном сценарии;
• отслеживать расход browser traffic.

Публичный API и CDP-интерфейс Captcha

Документация для пользователей публичного Browser API 2Captcha и CDP-интерфейса для управления решением CAPTCHA внутри облачного браузера.

Browser API позволяет создавать и управлять браузерными логинами, профилями браузера, настройками прокси, лимитами и статистикой трафика, а также получать готовый WebSocket URL для подключения к облачному браузеру через Chrome DevTools Protocol (CDP).

CDP-интерфейс Captcha доступен внутри подключённой браузерной сессии и позволяет включать авто-решение CAPTCHA, запускать решение вручную и отслеживать события решения.

1. Базовые сведения

Base URL

https://api.2captcha.com

Авторизация

Для всех запросов используется обычный API-ключ 2Captcha. Один и тот же ключ применяется для распознавания CAPTCHA, Fingerprint API, Proxy API и Browser API.

В запросах можно передавать параметр key:

key=YOUR_API_KEY

Для совместимости также поддерживается clientKey:

clientKey=YOUR_API_KEY

Формат запросов

GET-методы принимают параметры в query string.

POST, PUT и DELETE-методы принимают JSON-тело и требуют заголовок:

Content-Type: application/json

Формат успешного ответа

Успешные ответы содержат:

{
  "status": "OK"
}

Дополнительные данные возвращаются в полях ответа: account, profiles, connectionUri, browserTraffic, statistics и других, в зависимости от метода.

Формат ошибки

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

2. Быстрый старт

Шаг 1. Создайте браузерный логин

Браузерный логин можно создать без сохранённого прокси, а прокси передать позднее при получении 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"
  }'

Пример ответа:

{
  "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"
  }
}

Сохраните account.id. Он понадобится для получения connectionUri и управления профилями.

При создании браузерного логина также автоматически создаётся Default profile. Его profileId генерируется случайным образом и имеет вид p<random>, например p0123456789abcdef0123456789abcdef. Не формируйте ID Default profile из account.id самостоятельно.

Шаг 2. Получите WebSocket URL для подключения

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"
    }
  }'

Пример ответа:

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

Метод /browser/connection возвращает готовый URL и, если указан новый profileId, сразу создаёт запись профиля. Браузерная сессия при этом ещё не запускается: она начинается после подключения клиента к WebSocket URL.

Шаг 3. Подключитесь через 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');

Шаг 4. Подключитесь через 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. Прокси

Работа без сохранённого прокси

На данный момент браузерный логин можно создать с proxyMode: "none". Его Default profile также создаётся без сохранённого прокси и работает через бесплатный IPv6-прокси. Отдельно созданный профиль с proxyMode: "none" работает так же.

Важно: IPv6-режим без явно заданного прокси является временным и будет отключён. Для стабильной интеграции заранее настройте прокси 2Captcha, сохранённый customProxy или передавайте прокси в строке подключения.

После отключения IPv6 fallback, если при подключении прокси не найден, авторизация браузера вернёт ошибку:

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

proxyMode: "none" означает, что у браузерного логина или профиля не сохранён прокси. Пока IPv6 fallback доступен, такой профиль может работать без другого прокси. После его отключения прокси потребуется передать другим способом.

Режимы прокси для браузерных логинов

Режимы прокси для профилей

Профили поддерживают те же режимы, что и браузерные логины, а также режим наследования:

Приоритет выбора прокси

При авторизации браузера прокси выбирается в таком порядке:

1. Пользовательский прокси, переданный прямо при получении connectionUri или встроенный в WebSocket URL.
2. Настройки прокси, сохранённые у профиля.
3. Настройки прокси, сохранённые у браузерного логина.

Если после проверки всех уровней прокси не найден, сейчас используется временный IPv6 fallback. После его отключения подключение будет отклонено с ошибкой ERROR_PROXY_REQUIRED.

Объект customProxy

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

Если прокси не требует авторизации, поля login и password можно не передавать.

Передача прокси внутри WebSocket URL

Прокси можно встроить в username браузера в формате base64url.

Исходный URL прокси:

http://proxyuser:proxypass@1.1.1.1:8080

Base64url:

aHR0cDovL3Byb3h5dXNlcjpwcm94eXBhc3NAMS4xLjEuMTo4MDgw

Формат username:

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

Сегменты -dt-{deviceType}, -clickcaptcha (или -nocaptcha) и -proxy-{encodedProxy} — опциональные и добавляются в username в этом порядке, сразу после -pid-{profileId}:

• -dt-{deviceType} — тип устройства браузера. По умолчанию windows, можно указать -dt-android.
• -clickcaptcha — включает решение reCAPTCHA кликами. Флаг без значения.
• -nocaptcha — отключает решение CAPTCHA. Флаг без значения, взаимоисключающий с -clickcaptcha.
• -proxy-{encodedProxy} — передаёт пользовательский прокси прямо в URL подключения. Добавляется последним, перед паролем.

Параметры deviceType, clickcaptcha и nocaptcha сейчас передаются только через сегменты username при ручной сборке WebSocket URL. Метод POST /browser/connection не принимает эти поля.

Полный WebSocket URL:

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

Пример сборки URL на 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`;

Для сценариев без deviceType, clickcaptcha и nocaptcha рекомендуется получать готовый connectionUri через метод POST /browser/connection.

4. Состояние Browser API аккаунта

GET /browser

Возвращает состояние Browser API аккаунта: доступный и использованный трафик, лимиты браузерных логинов и профилей, а также информацию о доступности прокси.

GET /browser?key=YOUR_API_KEY

Пример:

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

Пример ответа:

{
  "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
  }
}

Превышение лимита браузерных логинов

Если количество браузерных логинов достигло значения accounts.max, создание нового логина (POST /browser/accounts) отклоняется:

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

Ответ дополнительно содержит поле maxAccounts — это не общий формат ошибки (см. раздел 1), а расширение конкретно для этого кода.

Превышение лимита профилей

Если количество профилей на браузерный логин достигло значения profiles.maxPerAccount, поштучное создание нового профиля через POST /browser/profiles или POST /browser/connection отклоняется:

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

Ответ дополнительно содержит поле maxPerAccount — как и в случае с ERROR_MAX_ACCOUNTS, это расширение конкретно для этого кода.

В Dashboard массовая генерация CDP URL работает иначе: запись сгенерированного профиля создаётся и начинает учитываться в лимите только после первого фактического CDP-подключения. Эта отложенная активация не относится к поштучному созданию через публичный API.

5. Браузерные логины

Браузерный логин (Browser Account) — это основная сущность Browser API. Через неё создаются профили браузера и формируется connectionUri для подключения. В Dashboard эта же сущность называется аккаунтом браузера — это два названия одного и того же объекта.

Не путайте браузерный логин как сущность API с полем login в её JSON-представлении.

Например:

{

  "id": 58,

  "login": "bc15b7f53510063b2593",

  "password": "browserPassword"

}

Здесь:

• Browser Account (браузерный логин) — сама сущность API;

• login — логин браузера, используемый при подключении по CDP;

• password — пароль браузера, используемый при подключении по CDP.

Список браузерных логинов

GET /browser/accounts?key=YOUR_API_KEY

Пример:

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

Объект браузерного логина в ответе содержит вложенное поле profile с текущим профилем подключения. У нового аккаунта это изначально Default profile, но позднее поле может указывать на другой профиль. Ниже показан сокращённый пример нового аккаунта, где текущим профилем является 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 — числовой внутренний ID записи. Для CDP URL и методов Browser API используйте строковое поле profile.profileId. Default profile имеет proxyMode: "inherit", поэтому в примере он наследует страну de от браузерного логина.

Создать браузерный логин

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

Создать логин с сохранённым пользовательским прокси

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"
    }
  }'

Пример ответа:

{
  "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"
  }
}

Создать логин с прокси-аккаунтом 2Captcha

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"
  }'

Пример ответа:

{
  "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"
  }
}

Поле country задаёт страну выхода для выбранного прокси-аккаунта 2Captcha. Передавайте двухбуквенный код страны в нижнем регистре, например fr для Франции. Параметр применяется при proxyMode: "our_proxy" и включается в username итогового CDP URL в сегменте -country-{countryCode}-.

Например, для "country": "fr" CDP URL содержит -country-fr-:

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

Создать логин без сохранённого прокси

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

Пример ответа:

{
  "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"
  }
}

Пока доступен временный IPv6 fallback (см. раздел 3), connectionUri из этого ответа рабочий и без явно заданного прокси.

Обновить браузерный логин

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

Пример:

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"
  }'

Поле country можно передать, чтобы изменить страну выхода. Если при обновлении не передать country, текущая страна сохранится. Это правило действует и при смене proxyAccountId: прокси-аккаунт изменится, а ранее выбранная страна останется прежней.

Сгенерировать новый пароль браузерного логина

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

После регенерации старые WebSocket URL с прежним паролем перестанут подходить для новых подключений.

Удалить браузерный логин

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

Пример:

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

6. Профили браузера

Профиль браузера хранит настройки конкретной браузерной среды внутри браузерного логина. Один браузерный логин может иметь несколько профилей.

Ограничения профиля

• Профиль поддерживает только одно активное CDP-подключение одновременно. Попытка подключиться к уже занятому профилю (например, открыть второй connectionUri этого же профиля, пока первый ещё используется) отклоняется с ошибкой profile_locked. Дождитесь завершения текущей сессии или используйте другой профиль.
• Профиль можно обновить во время активного CDP-подключения. Текущая сессия продолжит работать с прежними настройками до завершения подключения.
• Максимальная продолжительность одной браузерной сессии — 30 минут.
• Профили хранятся 90 дней с момента создания или до удаления пользователем.
• В веб-интерфейсе Default profile можно удалить, если у браузерного логина есть другой профиль. Единственный или последний оставшийся профиль удалить нельзя. Это ограничение относится к Dashboard; поведение DELETE /browser/profiles описано отдельно ниже.

Список профилей

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

Пример:

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

Параметры:

Создать или обновить профиль

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

Пример профиля с наследованием прокси от браузерного логина:

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"
  }'

При создании или обновлении профиля с proxyMode: "inherit" применяются прокси-настройки и страна родительского браузерного логина. При переходе из другого режима в inherit:

• собственные прокси-настройки профиля сбрасываются;
• proxyAccountId, proxy и customProxy в объекте профиля имеют значение null, так как эффективные настройки берутся из аккаунта;
• поле country профиля принимает страну аккаунта;
• profileId, имя, накопленная статистика и дата создания сохраняются.

Пример профиля с отдельными настройками прокси 2Captcha:

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

При proxyMode: "our_proxy" поле country задаёт страну выхода для профиля. Если передать country, профиль будет создан с указанной страной. Если не передавать country, профиль наследует страну из настроек родительского браузерного логина.

При создании профиля или переходе из другого режима в our_proxy поле proxyAccountId обязательно. Если передать только proxyMode: "our_proxy" без proxyAccountId, API вернёт ошибку:

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

При корректном переходе из none в our_proxy с полем proxyAccountId:

• существующий профиль обновляется без изменения profileId;
• proxyMode меняется на our_proxy;
• proxyAccountId и объект proxy заполняются данными выбранного прокси-аккаунта 2Captcha;
• customProxy остаётся null;
• если country не передан, сохраняется прежняя страна профиля;
• имя, накопленная статистика и дата создания сохраняются.

Если передать тот же accountId и существующий profileId, метод обновит профиль, а не создаст новый. При смене proxyMode с inherit на none:

• profileId, имя, накопленная статистика и дата создания сохраняются;
• proxyAccountId сбрасывается в null;
• proxy и customProxy сбрасываются в null;
• сохранённое значение country не изменяется.

В Dashboard для профиля с proxyMode: "none" показывается предупреждение: передайте прокси в URL подключения, иначе сейчас будет использован бесплатный IPv6-прокси. Этот fallback будет отключён.

Пример профиля с отдельным сохранённым пользовательским прокси:

{
  "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"
  }
}

При создании профиля или переходе из другого режима в custom_proxy объект customProxy обязателен. Если передать proxyMode: "custom_proxy" без данных customProxy, API вернёт ошибку:

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

При корректном переходе в custom_proxy:

• существующий профиль обновляется без изменения profileId;
• proxyMode меняется на custom_proxy;
• proxyAccountId сбрасывается в null;
• объект proxy сбрасывается в null;
• переданные данные сохраняются в customProxy;
• сохраняются прежние country, имя, статистика и дата создания профиля.

При proxyMode: "custom_proxy" фактическая страна выхода определяется самим внешним прокси. Сохранённое поле country, страна на карточке профиля и сегмент -country-{countryCode}- в CDP URL не переопределяют географию customProxy и могут не совпадать с реальной страной выхода.

Удалить профиль

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

Удалить один профиль:

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

Удалить все профили браузерного логина и заново создать Default profile:

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

Браузерный логин не может остаться без профиля. При программном удалении последнего профиля API сбрасывает его данные и создаёт новый Default profile с новым случайным profileId.

Это правило действует в обоих случаях:

• если последним был пользовательский профиль, он заменяется новым Default profile;
• если у аккаунта был только Default profile, он сбрасывается и заменяется новым Default profile.

В обоих случаях старый profileId больше не используется. Получите новый profileId из обновлённых данных браузерного логина.

7. Прокси-аккаунты 2Captcha

Browser API может использовать прокси-аккаунты 2Captcha, купленные или подключённые пользователем.

Список прокси-аккаунтов

GET /browser/proxy_accounts?key=YOUR_API_KEY

Пример:

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

Пример ответа:

{
  "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
      }
    ]
  }
}

Используйте id из ответа как proxyAccountId в настройках браузерного логина или профиля.

8. Получение connectionUri

POST /browser/connection

Метод возвращает готовый WebSocket URL для браузерного логина или профиля. Если в запросе передан новый profileId, профиль сразу создаётся в базе данных и учитывается в лимите профилей.

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

Использовать сохранённые настройки прокси:

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

Параметр profileId можно не передавать:

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

В этом случае метод использует профиль из текущего поля account.profile. Это не обязательно Default profile: если в account.profile находится другой профиль, его profileId будет включён в connectionUri. В ответе выбранный профиль также возвращается в верхнеуровневом поле profile.

Использовать пользовательский прокси только для этого подключения:

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

Пример ответа:

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

Важно: создание записи профиля не запускает браузерную сессию. Сессия начинается, когда Playwright, Puppeteer или другой CDP-клиент подключается к connectionUri.

9. История и статистика трафика

История операций с трафиком

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

Пример:

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

Статистика трафика

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

Необязательные фильтры:

Пример:

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

10. Частые коды ошибок Browser API

CDP-интерфейс Captcha

11. Назначение

CDP-домен Captcha позволяет управлять решением CAPTCHA на текущей вкладке облачного браузера.

Доступны два режима:

1. Авто-решение после загрузки страницы.
2. Ручной запуск решения через команду Captcha.solve.

События CDP позволяют отслеживать прогресс: обнаружение CAPTCHA, отправку запроса в сервис, успешное решение или ошибку.

12. Подключение к CDP-сессии

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

CaptchaOptions

Один элемент массива options. Обычно передаётся один объект.

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

SolveResult

Ответ команды Captcha.solve возвращается в поле result.

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

14. Команды CDP

Captcha.setAutoSolve

Включает или отключает автоматическое решение CAPTCHA на вкладке.

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

Параметры:

Ответ: без тела при успехе.

Возможная CDP-ошибка:

No active frame

Captcha.solve

Запускает явное решение CAPTCHA на текущей вкладке.

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

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

Параметры:

Пример успешного ответа:

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

Пример результата, если CAPTCHA не найдена:

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

Возможные CDP-ошибки без SolveResult:

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

15. События CDP

Подписка в 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');
});

События:

Цепочка событий в авто-режиме:

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

События нужны для отслеживания прогресса. Токен возвращается только в ответе команды Captcha.solve.

16. Рекомендуемые сценарии CDP

Авто-решение CAPTCHA

Используйте авто-решение, если нужно, чтобы браузер сам решал CAPTCHA после загрузки страницы.

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;

Рекомендуемый порядок:

Captcha.setAutoSolve({ autoSolve: true, options })
  → навигация на страницу с CAPTCHA
  → ожидание события Captcha.solveFinished или Captcha.solveFailed

В авто-режиме токен забирать и подставлять самостоятельно не нужно: он автоматически записывается на странице и, если нужно, форма отправляется сама (см. responseSelector и submitForm в CaptchaOptions, раздел 13). События нужны только чтобы отследить момент готовности; сам токен нигде в событии не передаётся.

Ручной запуск решения

Используйте ручной запуск, если нужно контролировать момент начала решения и получить токен в ответе команды.

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);
}

Рекомендуемый порядок:

Captcha.setAutoSolve({ autoSolve: false, options })
  → навигация
  → пауза 3–5 секунд, чтобы виджет успел зарегистрироваться
  → Captcha.solve({ detectTimeout, options })
  → проверка result.status

Не вызывайте Captcha.solve из обработчика Captcha.detected. Событие detected означает, что виджет уже найден; для ручного режима достаточно одного вызова Captcha.solve после короткой паузы.

17. Таймауты CDP

Если CDP-клиент имеет собственный таймаут на команду session.send, увеличьте его для Captcha.solve, иначе клиент может прервать ожидание раньше, чем сервис вернёт результат.

18. Полный пример: Browser API + Playwright + авто-решение CAPTCHA

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. Полный пример: Browser API + Playwright + ручной 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. Рекомендации по интеграции

1. Получайте connectionUri через POST /browser/connection, а не собирайте WebSocket URL вручную, если нет особой необходимости.
2. Всегда передавайте рабочий прокси: через customProxy, настройки профиля, настройки браузерного логина или прокси-аккаунт 2Captcha.
3. Для стабильной изоляции используйте отдельные профили под разные сценарии.
4. Для сценариев, где нужен только факт успешного прохождения CAPTCHA, используйте авто-решение и события.
5. Для сценариев, где нужен токен, используйте ручной Captcha.solve.
6. Увеличивайте таймаут CDP-клиента для ручного решения CAPTCHA.
7. Проверяйте result.status, а не только наличие ответа от CDP-команды.
8. Логируйте события Captcha.detected, Captcha.waitForSolve, Captcha.solveFinished и Captcha.solveFailed для диагностики.

Работа через Dashboard

Эта часть описывает работу с Browser API через Dashboard 2Captcha: создание браузерных аккаунтов и профилей, настройку прокси, получение CDP URL и наблюдение за сессиями через Live.

1. Основная логика работы

В Browser API есть две основные сущности: аккаунт браузера и профиль браузера.

Аккаунт браузера хранит общие настройки: логин, пароль, прокси, страну и общий расход трафика по всем профилям этого аккаунта.

Профиль браузера — это отдельная браузерная сессия внутри аккаунта. У каждого профиля есть свой CDP URL, статус, расход трафика, количество запросов и ссылка Live.

Проще всего думать так:

Аккаунт браузера = общие настройки и доступы
Профиль браузера = конкретная сессия для запуска
CDP URL = адрес подключения к профилю из Playwright / Puppeteer
Live = визуальный просмотр конкретного профиля

Обычный процесс выглядит так:

1. Создать аккаунт браузера
2. Выбрать, как он будет работать с прокси
3. Использовать Default profile или создать дополнительные профили
4. Скопировать CDP URL нужного профиля
5. Подключиться из кода или открыть Live

2. Разделы Browser API

В Browser API есть несколько основных вкладок.

Аккаунты браузера

Здесь создаются аккаунты браузера и отображаются карточки уже созданных аккаунтов.

На этой вкладке можно:

• создать аккаунт браузера;
• выбрать прокси для аккаунта;
• создать аккаунт без прокси, чтобы настроить прокси позже;
• посмотреть логин и пароль аккаунта;
• скопировать CDP URL выбранного профиля;
• открыть Live;
• создать дополнительные профили;
• перейти к активным профилям;
• изменить настройки прокси или страну;
• удалить профили или аккаунт.

Профили браузера

Здесь отображаются профили браузера.

Можно открыть:

• общий список профилей;
• список профилей выбранного аккаунта браузера.

На этой вкладке можно работать с конкретными профилями: смотреть статус, копировать CDP URL, открывать Live, проверять трафик и удалять профили.

Настройка подключения

Здесь можно выбрать параметры подключения и получить пример кода.

Доступны примеры для:

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

Документация

Раздел с описанием Browser API.

Прокси

Раздел для управления прокси и трафиком.

2.1. Демонстрационный аккаунт для первого знакомства

Для первого знакомства с Browser API вам не обязательно сразу создавать собственный аккаунт браузера и настраивать прокси. При старте в разделе Аккаунты браузера доступен демонстрационный аккаунт браузера с именем Default browser account, с профилем Default profile.

Этот аккаунт можно использовать, чтобы быстро посмотреть, как работает подключение по CDP и как выглядит браузерная сессия в Live.

Чтобы проверить демонстрационный аккаунт:

1. Откройте раздел Browser API → Аккаунты браузера.
2. Найдите демонстрационный аккаунт в списке аккаунтов.
3. В блоке CDP URL выберите профиль Default profile.
4. Нажмите Live.
5. Убедитесь, что открывается удалённая браузерная сессия.

Демонстрационный аккаунт работает через бесплатный IPv6-прокси без дополнительной настройки. Этого достаточно для первого знакомства с Live-просмотром и общей логикой CDP-подключения, но у IPv6 есть ограничения.

Некоторые сайты могут:

• не поддерживать IPv6;
• открываться нестабильно;
• показывать ошибку подключения;
• блокировать IPv6-трафик;
• не загружать часть ресурсов;
• работать иначе, чем через обычный IPv4-прокси.

Если сайт не открылся через демонстрационный аккаунт, это не обязательно означает проблему с Browser API. Возможно, конкретный сайт не работает с IPv6 или ограничивает такой тип подключения.

Для полноценной работы с нужными сайтами создайте собственный аккаунт браузера и настройте для него подходящий прокси:

• Прокси 2Captcha — если хотите использовать прокси-аккаунт 2Captcha и выбрать страну подключения;
• Свой прокси — если хотите подключить внешний HTTP, HTTPS или SOCKS5-прокси;
• Без прокси на аккаунте — если планируете передавать прокси позже при создании профиля или в URL подключения.

Демонстрационный аккаунт рекомендуется использовать только для первичной проверки интерфейса, Live-просмотра и понимания того, как устроена браузерная сессия.

3. Создание аккаунта браузера

Аккаунт браузера создаётся на вкладке Аккаунты браузера.

Слева находится форма Создать аккаунт. Справа отображается список уже созданных аккаунтов.

При создании аккаунта нужно выбрать вариант работы с прокси:

1. Прокси 2Captcha
2. Свой прокси
3. Без прокси

После создания аккаунта справа появляется его карточка с основной информацией.

4. Создание аккаунта с прокси 2Captcha

Этот вариант используется, если нужно работать через прокси 2Captcha.

Перед созданием аккаунта убедитесь, что прокси-трафик оплачен и доступен.

Порядок действий:

1. Откройте вкладку Аккаунты браузера.
2. В форме Создать аккаунт укажите название аккаунта.
3. Оставьте автоматическую генерацию пароля или включите Задать свой пароль.
4. В режиме прокси выберите Прокси 2Captcha.
5. В поле Аккаунт прокси выберите нужный прокси-аккаунт.
6. Выберите страну.
7. Нажмите Создать.

После создания аккаунт браузера будет настроен под выбранный прокси-аккаунт и выбранную страну.

На карточке аккаунта будет отображаться информация по браузеру и прокси: логин, пароль, использованный трафик, прокси-аккаунт, география, CDP URL выбранного профиля и ссылка Live.

Если для аккаунта используется прокси 2Captcha, у аккаунта можно изменить страну.

5. Создание аккаунта со своим прокси

Этот вариант используется, если нужно подключить внешний прокси.

Порядок действий:

1. Откройте вкладку Аккаунты браузера.
2. Введите название аккаунта.
3. Оставьте автоматическую генерацию пароля или задайте свой пароль.
4. В режиме прокси выберите Свой прокси.
5. Заполните поля прокси:
   • протокол;
   • хост;
   • порт;
   • логин;
   • пароль.
6. Нажмите Создать.

После создания аккаунт появится справа в списке аккаунтов.

В блоке прокси на карточке аккаунта будет отображаться пользовательский прокси.

Примеры прокси с авторизацией:

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

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

Если прокси не требует авторизации, логин и пароль можно не заполнять.

6. Создание аккаунта без прокси

Аккаунт можно создать без прокси, если прокси нужно добавить позже.

Порядок действий:

1. Откройте вкладку Аккаунты браузера.
2. Введите название аккаунта.
3. Оставьте автоматическую генерацию пароля или задайте свой пароль.
4. Выберите вариант без прокси.
5. Нажмите Создать.

Такой аккаунт можно использовать как заготовку.

Прокси можно добавить позже:

• через изменение настроек аккаунта;
• через создание профиля с отдельными настройками прокси;
• через CDP URL, если прокси передаётся в URL подключения.

Подробнее о передаче пользовательского прокси через CDP URL см. раздел 13.

Если для профиля отключено наследование и не задан другой прокси, интерфейс показывает предупреждение. Сейчас без прокси в URL используется бесплатный IPv6-прокси, но этот fallback будет отключён. Заранее настройте прокси или передавайте его в URL подключения.

7. Карточка аккаунта браузера

После создания аккаунта его карточка отображается справа на вкладке Аккаунты браузера.

На карточке аккаунта есть основная информация по браузеру:

• название аккаунта;
• логин;
• пароль;
• общий использованный трафик по всем профилям аккаунта;
• настройки прокси;
• CDP URL выбранного профиля;
• кнопка копирования CDP URL;
• ссылка Live;
• выбор профиля для подключения;
• количество активированных профилей (профили, созданные через генерацию CDP URL, начинают учитываться после первого подключения);
• кнопка Создать профили;
• ссылка Активные профили;
• кнопка Удалить профили;
• кнопки редактирования и удаления аккаунта.

С карточки аккаунта можно:

Скопировать CDP URL выбранного профиля
Открыть Live для выбранного профиля
Изменить настройки прокси
Изменить страну, если используется прокси 2Captcha
Создать дополнительные профили
Перейти к активным профилям
Удалить все профили аккаунта
Удалить аккаунт

8. Default profile

При создании аккаунта браузера автоматически создаётся Default profile.

Он нужен, чтобы сразу после создания аккаунта можно было:

• скопировать CDP URL;
• открыть Live;
• подключиться к браузеру из кода.

Когда создаются дополнительные профили, они появляются в списке выбора профилей на карточке аккаунта. После этого можно выбрать нужный профиль и открыть Live именно для него.

В веб-интерфейсе Default profile можно удалить, если у аккаунта есть другой профиль. Единственный или последний оставшийся профиль аккаунта удалить нельзя.

9. Активные профили

На карточке аккаунта есть ссылка Активные профили.

Она открывает вкладку Профили браузера и показывает профили выбранного аккаунта.

В этом разделе отображаются только активированные профили. Если список CDP URL был сгенерирован через массовую генерацию профилей, такие профили появятся здесь только после первого успешного подключения.

Во вкладку Профили браузера также можно перейти через верхнее меню.

Логика отображения такая:

Аккаунт выбран слева → справа отображаются профили этого аккаунта
Аккаунт не выбран → справа отображается общий список профилей

10. Создание профилей через карточку аккаунта

Дополнительные профили нужны, если требуется несколько отдельных браузерных сессий.

Например:

• для параллельных запусков;
• для разных воркеров;
• для разных задач;
• для разных стран;
• для разных прокси;
• для изоляции сессий друг от друга.

Чтобы создать профили:

1. Откройте вкладку Аккаунты браузера.
2. Найдите нужный аккаунт.
3. Нажмите Создать профили.
4. Укажите количество профилей.
5. При необходимости переопределите прокси для генерируемых профилей. По умолчанию они наследуют настройки прокси аккаунта; при необходимости можно задать другой режим:
   • Прокси 2Captcha — выберите прокси-аккаунт и страну;
   • Свой прокси — заполните параметры прокси.
6. Сгенерируйте список CDP URL.
7. Скопируйте результат.
8. Передайте CDP URL в код или сохраните в нужное место.

Важно: сгенерированные URL нужно сразу скопировать. После закрытия окна генерации профили, которые не были активированы подключением, не сохраняются и не попадают в базу данных. Такие профили не учитываются в лимите количества профилей.

Профиль считается активированным после первого подключения по его CDP URL. Только после этого он создаётся в базе данных, начинает отображаться в разделе «Активные профили» и учитывается в счётчике профилей.

Проще правило:

Сгенерировали URL → сразу скопировали → использовали или сохранили.

11. Карточка профиля браузера

Во вкладке Профили браузера каждый профиль отображается отдельной карточкой в списке. Если аккаунт браузера слева не выбран, отображается общий список всех профилей; если аккаунт выбран — список фильтруется и показывает только профили этого аккаунта.

На карточке профиля есть основная информация профиля:

• статус;
• количество запросов;
• использованный трафик;
• дата создания;
• информация о прокси;
• CDP URL;
• кнопка копирования CDP URL;
• ссылка Live;
• удаление конкретного профиля.

Также можно удалить все профили, относящиеся к выбранному аккаунту браузера, если нужно очистить список. Кнопка удаления отображается только при выбранном аккаунте браузера.

Карточка профиля используется, когда нужно работать с конкретной сессией, а не со всем аккаунтом.

12. Создание профиля во вкладке «Профили браузера»

Новый профиль можно создать для выбранного аккаунта браузера.

При создании профиля нужно выбрать прокси-настройки.

Доступные варианты:

1. Наследовать настройки от аккаунта браузера
2. Использовать прокси 2Captcha
3. Использовать свой прокси
4. Без прокси, с отключением наследования

При создании профиля через эту вкладку профиль создаётся сразу и сразу сохраняется в базе данных, поэтому сразу отображается в списке профилей и учитывается в лимите профилей.

Для сравнения: при генерации списка профилей через функцию Создать профили (Bulk Generate) создаются только CDP URL. Такой профиль попадёт в базу данных, появится в разделе Активные профили и начнёт учитываться в лимите только после первого подключения по своему CDP URL.

Наследовать от аккаунта браузера

Профиль использует те же прокси-настройки, что и аккаунт браузера.

Это удобный вариант, если все профили аккаунта должны работать одинаково.

Прокси 2Captcha

Профиль использует прокси 2Captcha.

Нужно выбрать:

• прокси-аккаунт;
• страну.

Этот вариант подходит, если конкретный профиль должен использовать другие настройки, чем аккаунт браузера.

Свой прокси

Профиль использует внешний прокси.

Нужно заполнить поля:

• протокол;
• хост;
• порт;
• логин;
• пароль.

Если прокси не требует авторизации, логин и пароль можно не заполнять.

Такой профиль будет использовать свой прокси, даже если у аккаунта браузера настроены другие параметры.

Фактическая страна выхода определяется самим внешним прокси. Страна, отображаемая на карточке профиля, может не совпадать с реальной географией подключения.

Без прокси

Можно отключить наследование прокси и создать профиль без прокси.

Сейчас без прокси в URL используется бесплатный IPv6-прокси. Этот fallback будет отключён, поэтому для стабильной работы настройте прокси. Подробнее см. раздел 6.

13. CDP URL

CDP URL — это WebSocket URL для подключения к профилю браузера.

CDP URL можно взять в двух местах:

1. На карточке аккаунта браузера — для выбранного профиля
2. На карточке конкретного профиля — во вкладке «Профили браузера»

CDP URL используется в Playwright, Puppeteer и других клиентах, которые поддерживают Chrome DevTools Protocol.

Пример формата:

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

Если прокси передаётся в URL подключения, в CDP URL также добавляется часть с прокси.

CDP URL содержит данные доступа к браузеру, поэтому его нельзя публиковать в открытых местах.

Если прокси задан одновременно на нескольких уровнях, применяется следующий порядок приоритета:

1. Прокси, переданный в строке подключения (CDP URL).
2. Прокси, заданный у профиля.
3. Прокси, заданный у аккаунта.

Пример использования пользовательского прокси

Если прокси передаётся в строке подключения, в CDP URL используется не сама строка прокси, а её Base64URL-представление.

Например, строка прокси:

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

После кодирования в Base64URL получается, например:

c29ja3M1Oi8vbG9naW46cGFzc3dvcmRAcHJveHkuZXhhbXBsZS5jb206MTA4MA

Используется при формировании CDP URL:

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

Примечание: в Browser API кодирование выполняется автоматически при генерации строки подключения в разделе Настройка подключения, поэтому вручную кодировать строку прокси обычно не требуется.

14. Live

Live открывает визуальный просмотр браузерной сессии.

Важно: Live нельзя открыть для профиля, который уже используется активным CDP-подключением (ошибка profile_locked, подробнее в разделе 20 «Ограничения и хранение»). Для Live используйте свободный профиль или дождитесь завершения существующего подключения.

Если профиль или аккаунт удалить во время активного CDP-подключения, уже открытая браузерная сессия продолжит работать до завершения текущего подключения. При этом повторное подключение к этому профилю по тому же CDP URL невозможно.

Профиль можно обновить во время активного CDP-подключения. Уже работающая сессия продолжит работать с прежними настройками до завершения текущего подключения.

Live можно открыть:

• с карточки аккаунта браузера;
• с карточки конкретного профиля.

Если у аккаунта несколько профилей, сначала выберите нужный профиль на карточке аккаунта, а затем откройте Live.

Live полезен, когда нужно проверить:

• открылась ли страница;
• какой контент видит браузер;
• появилась ли CAPTCHA;
• сработал ли клик;
• куда произошёл редирект;
• почему элемент не найден;
• какой прокси применился;
• не завис ли браузер на загрузке.

15. Настройка подключения

Во вкладке Настройка подключения можно получить пример кода для подключения.

Порядок действий:

1. Откройте вкладку Настройка подключения.
2. Выберите аккаунт браузера.
3. Выберите тип прокси.
4. Если выбран Прокси 2Captcha, выберите прокси-аккаунт и страну.
5. Если выбран Свой прокси, заполните стандартные поля: протокол, хост, порт, логин и пароль.
6. Выберите нужный пример кода.
7. Скопируйте код.

Доступны примеры:

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

Этот раздел удобен, если нужно быстро получить шаблон подключения без ручной сборки CDP URL.

16. Быстрый сценарий: аккаунт с прокси 2Captcha

1. Откройте Аккаунты браузера.
2. Введите название аккаунта.
3. Выберите Прокси 2Captcha.
4. Выберите прокси-аккаунт.
5. Выберите страну.
6. Нажмите Создать.
7. На карточке аккаунта выберите Default profile.
8. Скопируйте CDP URL или откройте Live.
9. Используйте CDP URL в Playwright или Puppeteer.

17. Быстрый сценарий: аккаунт со своим прокси

1. Откройте Аккаунты браузера.
2. Введите название аккаунта.
3. Выберите Свой прокси.
4. Заполните протокол, хост, порт, логин и пароль.
5. Нажмите Создать.
6. На карточке аккаунта выберите Default profile.
7. Скопируйте CDP URL или откройте Live.

18. Быстрый сценарий: аккаунт без прокси

1. Откройте Аккаунты браузера.
2. Введите название аккаунта.
3. Выберите вариант без прокси.
4. Нажмите Создать.
5. Добавьте прокси позже через настройки аккаунта, профиль или URL подключения.

Сейчас без прокси в URL профиль использует бесплатный IPv6-прокси. Этот fallback будет отключён.

19. Быстрый сценарий: несколько профилей для параллельной работы

1. Создайте аккаунт браузера.
2. Убедитесь, что прокси настроен правильно.
3. На карточке аккаунта нажмите Создать профили.
4. Укажите количество профилей.
5. Сгенерируйте список CDP URL.
6. Сразу скопируйте результат.
7. Передайте каждый CDP URL отдельному воркеру или процессу.
8. После первого подключения профили станут активными.
9. Управлять активными профилями можно во вкладке Профили браузера.

Рекомендация:

Один профиль = одна независимая сессия
Один CDP URL = один воркер или одна задача

Повторное подключение к уже занятому профилю невозможно (ошибка profile_locked, см. раздел 20). Для каждого параллельного процесса используйте отдельный профиль.

20. Ограничения и хранение

• Максимальная продолжительность одной браузерной сессии — 30 минут.
• Профили хранятся 90 дней с момента создания или до их удаления пользователем.
• Профиль поддерживает только одно активное CDP-подключение одновременно. При попытке повторно подключиться к уже занятому профилю (включая открытие Live) возвращается ошибка profile_locked. Дождитесь завершения текущей браузерной сессии или используйте другой профиль.

21. Короткая памятка

Аккаунт браузера создаётся с прокси или без прокси.
Если выбран прокси 2Captcha, нужно выбрать прокси-аккаунт и страну.
Если выбран свой прокси, нужно заполнить протокол, хост, порт, логин и пароль.
После создания аккаунта автоматически появляется Default profile.
CDP URL берётся у выбранного профиля.
Один профиль поддерживает только одно активное подключение одновременно.
Live открывается для конкретного профиля.
Дополнительные профили нужны для параллельных запусков.
Сгенерированные URL профилей нужно сразу копировать.
Неактивированные профили не сохраняются после закрытия окна генерации.
Во вкладке «Профили браузера» можно управлять профилями по отдельности.
Во вкладке «Настройка подключения» можно получить код для Puppeteer и Playwright.

22. Минимальный чек-лист перед запуском

Перед подключением из кода проверьте:

Аккаунт браузера создан
Прокси настроен
Страна выбрана, если используется прокси 2Captcha
Профиль создан или выбран Default profile
CDP URL скопирован полностью
Для параллельных задач используются разные профили
При проблемах открыт Live для проверки состояния браузера