For AI agents: a documentation index is available at /llms.txt
Skip to main content

CAPTCHA Solving

BrowserQL includes built-in support for CAPTCHA challenges, including those embedded in iframes or shadow DOMs, and in most cases the solve mutation handles them with no configuration required. For custom image-based CAPTCHAs that standard detection can't handle, use solveImageCaptcha.

Prerequisites
DEPRECATION WARNING

The verify mutation is deprecated and will be removed in a future version. Use the solve mutation instead.

Solve​

The solve mutation detects and solves CAPTCHAs on a page. It automatically identifies the CAPTCHA type, so you don't need to specify it.

info

When solving reCAPTCHAs, the checkbox may not appear ticked after solving. This is expected. After solving, click the form's submit button to proceed.

mutation SolveCaptcha {
  goto(url: "https://protected.domain") {
    status
  }

  solve {
    found
    solved
    time
  }
}

Specifying a type​

The type argument is optional. Specifying the CAPTCHA type can reduce verification time by a few milliseconds when you know which type is present. See the full list of supported types in the CAPTCHA types schema reference.

mutation SolveCaptchaWithType {
  goto(url: "https://protected.domain") {
    status
  }

  solve(type: recaptcha) {
    found
    solved
    time
  }
}

Form submission after solving​

After solving a CAPTCHA, click the submit button to proceed:

mutation SolveAndSubmit {
  goto(url: "https://protected.domain") {
    status
  }

  solve {
    found
    solved
    time
  }

  click(selector: "button[type='submit']") {
    time
  }
}

If no submit button is available, trigger form submission with the evaluate mutation:

mutation SolveAndTriggerSubmit {
  goto(url: "https://protected.domain") {
    status
  }

  solve {
    found
    solved
    time
  }

  evaluate(content: "window.onSubmit()") {
    time
  }
}

Replace window.onSubmit() with the JavaScript function that submits the form on your target site.

Solving Image CAPTCHAs​

Use solveImageCaptcha when solve doesn't detect a CAPTCHA on a page. This happens with custom image-based challenges, typically legacy sites that display a distorted text image and require users to type what they see. Unlike solve, this mutation requires CSS selectors for both the CAPTCHA image and the input field where the solution is entered.

mutation SolveImageCaptcha {
  goto(url: "https://captcha.com/demos/features/captcha-demo.aspx", waitUntil: networkIdle) {
    status
  }

  solveImageCaptcha(
    captchaSelector: "#demoCaptcha_CaptchaImage"
    inputSelector: "#captchaCode"
    timeout: 30000
  ) {
    found
    solved
    time
    token
  }
}

Form submission after solving​

After solving, submit the form by clicking the submit button:

mutation SolveImageCaptchaAndSubmit {
  goto(url: "https://captcha.com/demos/features/captcha-demo.aspx", waitUntil: networkIdle) {
    status
  }

  solveImageCaptcha(
    captchaSelector: "#demoCaptcha_CaptchaImage"
    inputSelector: "#captchaCode"
  ) {
    found
    solved
    time
    token
  }

  click(selector: "#validateCaptchaButton") {
    time
  }
}

FAQ & Troubleshooting​

The solve mutation returns found: false

The CAPTCHA element isn't in the DOM when solve runs. Add a waitForSelector before solve to ensure the CAPTCHA has loaded. If the CAPTCHA is inside an iframe, BQL should still detect it, but verify the page has fully rendered.

CAPTCHA solving is taking too long

Some challenges (especially image-based ones) can take 30 seconds to several minutes. Set a generous timeout on the solve mutation or omit it to use the default. For solveImageCaptcha, processing time depends on the number of images and their complexity.

Next steps​

CAPTCHA types reference

all supported CAPTCHA types in the BQL schema

Proxies

residential and external proxy routing

Stealth route

fingerprint mitigations and entropy injection