Skip to main content

CAPTCHA Solving

CAPTCHAs are a common roadblock in automation. BrowserQL includes built-in support for CAPTCHA challenges, including those embedded in iframes or shadow DOMs. In most cases, you only need the solve mutation. No configuration required. For custom image-based CAPTCHAs that standard detection can't handle, use solveImageCaptcha.

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

Next Steps​

CAPTCHA types reference

See all supported CAPTCHA types in the BrowserQL schema.

Proxies

Use residential and external proxies for enhanced anonymity and geographic flexibility.

Stealthy BQL

Learn more about our stealth routes for BQL