CAPTCHA Solving

Browserbase enables CAPTCHA solving by default for all sessions. How it works

Expect CAPTCHA solving to take up to 30 seconds, depending on the challenge type.
Pairing with proxies improves success rates.
For non-standard CAPTCHAs, you can provide custom selectors to guide the process.

Use CAPTCHA solving only for workflows that users and website owners authorize. Follow the site’s terms, respect access controls, and use supported integrations when available. To disable CAPTCHA solving, set solveCaptchas to false in browserSettings when creating a session.

CAPTCHA solving events

Browserbase emits a console log when it detects a CAPTCHA and begins solving. Listen to these events before your agent continues.

Node.js
Python

const recaptcha = await page.goto("https://www.google.com/recaptcha/api2/demo");

page.on("console", (msg) => {
  if (msg.text() == "browserbase-solving-started") {
    console.log("Captcha Solving In Progress");
  } else if (msg.text() == "browserbase-solving-finished") {
    console.log("Captcha Solving Completed");
  }
});

// Replace your existing Builder configuration with this code
const driver = new Builder()
  .withCapabilities({
    browserName: "chrome", // add browser name
    "goog:loggingPrefs": {
      driver: "ALL", // add driver logs
    },
  })
  .usingHttpAgent(customHttpAgent)
  .usingServer(session.seleniumRemoteUrl)
  .build();

// Add this code where you want to check for CAPTCHA solving
const driverLogs = await driver.manage().logs().get("driver");

// Example check for CAPTCHA solving events
driverLogs
  .filter((log) => log.message.includes("browserbase-solving"))
  .forEach((log) => console.log(log.message));

# Add this code where you want to check for CAPTCHA solving
def handle_console(msg):
    if msg.text == "browserbase-solving-started":
        print("Captcha Solving In Progress")
    elif msg.text == "browserbase-solving-finished":
        print("Captcha Solving Completed")

page.on("console", handle_console)

# Configure logging preferences when creating the driver
options = webdriver.ChromeOptions()
options.set_capability("goog:loggingPrefs", {"driver": "ALL"})
driver = webdriver.Remote(command_executor=session.selenium_remote_url, options=options)

# Add this code where you want to check for CAPTCHA solving
logs = driver.get_log("driver")
for log in logs:
    if "browserbase-solving-started" in log["message"]:
        print("Captcha Solving In Progress")
    elif "browserbase-solving-finished" in log["message"]:
        print("Captcha Solving Completed")

Custom CAPTCHA solving

If you encounter a non-standard, or custom CAPTCHA provider, you need to specify the explicit selector for the CAPTCHA image and button itself. For this custom CAPTCHA provider, you’ll need to specify two CSS selectors:

The selector for the CAPTCHA image element

Right-click on the CAPTCHA image and select 'Inspect' then pull the 'id' from the HTML source code of the image

<img class="LBD_CaptchaImage" id="c_turingtestpage_ctl00_maincontent_captcha1_CaptchaImage" src="/BotDetectCaptcha.ashx?get=image&amp;c=c_turingtestpage_ctl00_maincontent_captcha1&amp;t=759cbf332a684ae3abe16213fe76438c" alt="CAPTCHA">

The id in this example is c_turingtestpage_ctl00_maincontent_captcha1_CaptchaImage

The selector for the input field where the solution should be entered

Right-click on the input field and select 'Inspect' then pull the 'id' from the HTML source code of the input field

<input name="ctl00$MainContent$txtTuringText" type="text" value="Enter the characters shown above" maxlength="6" id="ctl00_MainContent_txtTuringText" class="swap_value field" initialvalue="Enter the characters shown above" title="Enter the characters shown above">

The id in this example is ctl00_MainContent_txtTuringText

Configure your browser settings with these selectors

browserSettings: {
  captchaImageSelector: "#c_turingtestpage_ctl00_maincontent_captcha1_CaptchaImage",
  captchaInputSelector: "#ctl00_MainContent_txtTuringText"
}

Disabling CAPTCHA solving

CAPTCHA solving typically takes between 5 and 30 seconds. If you’d like to disable captcha solving, you can set solveCaptchas to false in the browserSettings when creating a session.

Node.js
Python

SDK

import Browserbase from "@browserbasehq/sdk";

const bb = new Browserbase({apiKey: process.env.BROWSERBASE_API_KEY!});

async function createSessionWithoutCaptchaSolving() {
  const session = await bb.sessions.create({
    browserSettings: {
      solveCaptchas: false,
    },
  });
  return session;
}

const session = await createSessionWithoutCaptchaSolving();
console.log(session);

SDK

from browserbase import Browserbase
import os

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

def createSessionWithoutCaptchaSolving():
    session = bb.sessions.create(
        browser_settings={
          "solveCaptchas": False,
        }
    )
    return session

session = createSessionWithoutCaptchaSolving()
print(session)

Welcome

Platform

Use cases

Optimization

Account

CAPTCHA solving events

Custom CAPTCHA solving

Disabling CAPTCHA solving

​CAPTCHA solving events

​Custom CAPTCHA solving

​Disabling CAPTCHA solving

CAPTCHA solving events

Custom CAPTCHA solving

Disabling CAPTCHA solving