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.

Encounter a block you can’t get past? Verified supports it. Contact sales to learn more.

To disable CAPTCHA solving, set solveCaptchas to false in browserSettings when creating a session.

CAPTCHA solving events

Browserbase emits console logs when it starts, finishes, or fails to solve a CAPTCHA. Register your listener before navigation or a click that could trigger a challenge, so you don’t miss the events. For agent loops, hold further browser actions and human handoff while solving is in progress. After browserbase-solving-finished, verify that the expected page or element is accessible. After browserbase-solving-errored, keep watching for a new browserbase-solving-started within the original timeout: the site may trigger another challenge. Ask for human help only when no solve is active and the page remains blocked after a bounded readiness check. If the overall timeout expires during an active solve, report that state to your application rather than handing off the page. See Wait for CAPTCHA solves for copyable agent prompts, waiting behavior, and troubleshooting. The examples below collect events; they do not pause your agent automatically.

Node.js
Python

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");
  } else if (msg.text() == "browserbase-solving-errored") {
    console.log("Captcha Solving Failed");
  }
});

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

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

# Register before navigation or an action that could trigger a CAPTCHA.
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")
    elif msg.text == "browserbase-solving-errored":
        print("Captcha Solving Failed")


page.on("console", handle_console)

page.goto("https://www.google.com/recaptcha/api2/demo")

# 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")
    elif "browserbase-solving-errored" in log["message"]:
        print("Captcha Solving Failed")

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

Node.js

const sessionOptions = {
  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

Node.js

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

Python

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)

Agent Identity

Understand identity and access for browser automation.

Browser observability

Inspect browser activity and diagnose failed runs.

Welcome

Platform

Use cases

Optimization

Account

CAPTCHA solving events

Custom CAPTCHA solving

Disabling CAPTCHA solving

Agent Identity

Browser observability

CAPTCHA solving events

Custom CAPTCHA solving

Disabling CAPTCHA solving

Related guides

Agent Identity

Browser observability