Skip to main content

CAPTCHA Solving Guide

Automatic CAPTCHA detection and solving for protected websites.

Overview​

Many websites use CAPTCHAs to protect against bots and automated scraping. Browser7 provides automatic CAPTCHA detection and solving capabilities, allowing you to access protected content without manual intervention. The service supports the most common CAPTCHA types including Google reCAPTCHA v2/v3 and Cloudflare Turnstile.

Why Use CAPTCHA Solving?​

Access Protected Content​

Many valuable data sources are protected by CAPTCHAs:

  • E-commerce Sites: Product prices and availability
  • News Sites: Article content behind CAPTCHA walls
  • Booking Platforms: Flight and hotel pricing
  • Protected APIs: Web services with CAPTCHA challenges

Cost Optimization​

CAPTCHA detection adds ~60-250ms to render time. Smart usage patterns can minimize costs:

  • Two-Step Approach: First render without CAPTCHA detection (fastest), then re-render with solving if CAPTCHA is detected in the HTML
  • Known Sites: For sites known to have CAPTCHAs, always enable detection upfront
  • Unknown Sites: Disable detection by default, enable only when needed

Automation at Scale​

Manual CAPTCHA solving doesn't scale:

  • Human Intervention: Requires constant monitoring and manual solving
  • Time Intensive: Each manual solve takes 10-30 seconds
  • Reliability: Humans make mistakes and aren't available 24/7
  • Automation: Browser7 solves CAPTCHAs automatically in 2-5 seconds

How It Works​

When CAPTCHA solving is enabled, Browser7:

  1. Loads the Page: Navigates to the target URL as normal
  2. Detects CAPTCHA: Scans the page for CAPTCHA widgets (reCAPTCHA, Turnstile)
  3. Extracts Challenge: Identifies the CAPTCHA type and extracts the sitekey
  4. Solves Challenge: Uses third-party solving services to generate a valid token
  5. Submits Solution: Injects the token and triggers CAPTCHA completion
  6. Waits for Success: Ensures the page accepts the solution and loads protected content
  7. Returns Result: Provides the rendered HTML with CAPTCHA solved

The entire process is transparent - you receive the final rendered HTML as if the CAPTCHA was never there.

Supported CAPTCHA Types​

Browser7 currently supports the three most common CAPTCHA types:

reCAPTCHA v2​

Type: Image-based challenge (select traffic lights, crosswalks, etc.)

Characteristics:

  • Displays "I'm not a robot" checkbox
  • May show image grid challenge
  • Common on older websites and forums
  • Solving time: 10-20 seconds

Usage: Set captcha: 'recaptcha_v2' or use 'auto' for automatic detection

reCAPTCHA v3​

Type: Score-based, invisible CAPTCHA

Characteristics:

  • No visible checkbox or challenge
  • Analyzes user behavior and assigns a risk score
  • Common on modern websites
  • Solving time: 2-5 seconds (faster than v2)

Usage: Set captcha: 'recaptcha_v3' or use 'auto' for automatic detection

Cloudflare Turnstile​

Type: Cloudflare's reCAPTCHA alternative

Characteristics:

  • Cloudflare's proprietary CAPTCHA system
  • Similar to reCAPTCHA v2/v3 in appearance
  • Growing adoption as Cloudflare alternative
  • Solving time: 3-8 seconds

Usage: Set captcha: 'turnstile' or use 'auto' for automatic detection

CAPTCHA Modes​

Browser7 offers several CAPTCHA modes to balance speed and functionality:

Disabled (Default)​

{ captcha: 'disabled' }  // or omit the parameter

When to use:

  • Sites without CAPTCHAs
  • First attempt with unknown sites (two-step approach)
  • Performance-critical applications

Benefit: Saves ~60-250ms per render (no CAPTCHA detection overhead)

Auto-Detection​

{ captcha: 'auto' }

When to use:

  • Sites that might have CAPTCHAs
  • Unknown CAPTCHA types
  • Multi-site scraping where CAPTCHA presence varies

Behavior: Automatically detects and solves any supported CAPTCHA type

Trade-off: Slightly slower than specific mode (~100-200ms more for detection)

Specific Type​

{ captcha: 'recaptcha_v2' }    // reCAPTCHA v2 only
{ captcha: 'recaptcha_v3' }    // reCAPTCHA v3 only
{ captcha: 'turnstile' }       // Turnstile only

When to use:

  • Sites with known CAPTCHA types
  • Maximum performance (skip detection of other types)
  • Production systems with consistent CAPTCHA usage

Benefit: Fastest CAPTCHA solving (no detection overhead)

Best Practices​

Use Two-Step Detection​

The most cost-effective approach for sites with uncertain CAPTCHA presence:

Step 1: Render without CAPTCHA detection (fastest)

const result = await client.render('https://example.com', {
  captcha: 'disabled'  // Default, saves 60-250ms
});

Step 2: Check for CAPTCHA in HTML

if (result.html.includes('recaptcha') || result.html.includes('cf-turnstile')) {
  // CAPTCHA detected, re-render with solving
  const solvedResult = await client.render('https://example.com', {
    captcha: 'auto'
  });
}

Savings: Only pay for CAPTCHA solving when actually needed

Prefer Specific Over Auto​

When you know the CAPTCHA type, specify it:

// ❌ Slower (auto-detection overhead)
{ captcha: 'auto' }

// ✅ Faster (no detection, direct solving)
{ captcha: 'recaptcha_v3' }

Speed difference: ~100-200ms faster with specific type

Check CAPTCHA Result​

Every render includes CAPTCHA information:

{
  captcha: {
    detected: boolean,    // Was a CAPTCHA found?
    handled: boolean,     // Was it successfully solved?
    sitekey: string      // CAPTCHA sitekey (if detected)
  }
}

Always verify handled: true before processing the content:

if (!result.captcha.handled && result.captcha.detected) {
  console.error('CAPTCHA was detected but not solved');
  // Handle failure case
}

Combine with Wait Actions​

CAPTCHAs often trigger page changes after solving. Use wait actions to ensure content loads:

const result = await client.render('https://example.com', {
  captcha: 'auto',
  waitFor: [
    Browser7.waitForSelector('.content-after-captcha', 'visible'),
    Browser7.waitForDelay(2000)
  ]
});

Monitor CAPTCHA Costs​

Track when CAPTCHAs are being solved to optimize costs:

const stats = {
  total: 0,
  captchaSolved: 0,
  captchaFailed: 0
};

const result = await client.render(url, { captcha: 'auto' });

stats.total++;
if (result.captcha.handled) {
  stats.captchaSolved++;
} else if (result.captcha.detected) {
  stats.captchaFailed++;
}

console.log(`CAPTCHA solve rate: ${stats.captchaSolved / stats.total * 100}%`);

Common Use Cases​

Protected E-commerce Sites​

Monitor prices on sites with CAPTCHA protection:

async function monitorProtectedPrice(productUrl) {
  // First attempt without CAPTCHA (faster)
  let result = await client.render(productUrl);

  // Check if CAPTCHA present
  if (result.html.includes('recaptcha')) {
    // Re-render with CAPTCHA solving
    result = await client.render(productUrl, {
      captcha: 'recaptcha_v2',
      waitFor: [
        Browser7.waitForSelector('.price', 'visible')
      ]
    });
  }

  return extractPrice(result.html);
}

Cloudflare-Protected Sites​

Many sites use Cloudflare Turnstile:

const result = await client.render('https://cloudflare-protected-site.com', {
  captcha: 'turnstile',
  waitFor: [
    Browser7.waitForSelector('.main-content', 'visible')
  ]
});

Mixed CAPTCHA Sites​

Sites that might have different CAPTCHA types:

const result = await client.render('https://example.com', {
  captcha: 'auto',  // Handles any CAPTCHA type
  waitFor: [
    Browser7.waitForText('Welcome'),
    Browser7.waitForDelay(1000)
  ]
});

SDK Implementations​

See language-specific examples for CAPTCHA solving:

Python Examples​

from browser7 import Browser7

client = Browser7(api_key='b7_your_api_key_here')

# Auto-detect and solve any supported CAPTCHA type
result = client.render('https://example.com', captcha='auto')

# Target a specific CAPTCHA type
result = client.render('https://example.com', captcha='recaptcha_v2')
result = client.render('https://example.com', captcha='recaptcha_v3')
result = client.render('https://example.com', captcha='turnstile')

# Check CAPTCHA result
if result.captcha['detected'] and not result.captcha['handled']:
    print('CAPTCHA detected but not solved')

# Two-step approach: only solve when needed
result = client.render('https://example.com', captcha='disabled')

if 'recaptcha' in result.html or 'cf-turnstile' in result.html:
    result = client.render('https://example.com', captcha='auto')

PHP Examples​

<?php

use Browser7\Browser7Client;
use Browser7\WaitAction;

$client = new Browser7Client('b7_your_api_key_here');

// Auto-detect and solve any supported CAPTCHA type
$result = $client->render('https://example.com', [
    'captcha' => 'auto'
]);

// Target a specific CAPTCHA type
$result = $client->render('https://example.com', ['captcha' => 'recaptcha_v2']);
$result = $client->render('https://example.com', ['captcha' => 'recaptcha_v3']);
$result = $client->render('https://example.com', ['captcha' => 'turnstile']);

// Check CAPTCHA result
if ($result->captcha['detected'] && !$result->captcha['handled']) {
    echo 'CAPTCHA detected but not solved';
}

// Two-step approach: only solve when needed
$result = $client->render('https://example.com', ['captcha' => 'disabled']);

if (str_contains($result->html, 'recaptcha') || str_contains($result->html, 'cf-turnstile')) {
    $result = $client->render('https://example.com', ['captcha' => 'auto']);
}

Troubleshooting​

CAPTCHA Not Detected​

If captcha.detected: false but you see a CAPTCHA in the HTML:

  • ✅ Check the CAPTCHA type is supported (reCAPTCHA v2/v3, Turnstile only)
  • ✅ Try using captcha: 'auto' instead of a specific type
  • ✅ Verify the CAPTCHA is present on initial page load (not loaded via JavaScript after render)
  • ✅ Some CAPTCHAs only appear based on user behavior patterns

CAPTCHA Detected but Not Solved​

If captcha.detected: true but captcha.handled: false:

  • Check the result.error message for details
  • The CAPTCHA solving service may be temporarily unavailable
  • Some CAPTCHA configurations are more difficult to solve (higher rejection rate)
  • Try re-rendering or contact support if persistent

Content Still Missing After Solving​

If CAPTCHA was solved but expected content isn't present:

  • Check result.captcha.handled is true
  • Add wait actions to ensure content loads after CAPTCHA completion: 
    waitFor: [
      Browser7.waitForSelector('.protected-content', 'visible'),
      Browser7.waitForDelay(2000)
    ]
  • Some sites may have additional protections beyond CAPTCHAs
  • Verify the page structure matches your expectations

High CAPTCHA Costs​

If CAPTCHA solving costs are higher than expected:

  • Switch to two-step detection (render without CAPTCHA first, check HTML)
  • Use specific CAPTCHA types instead of 'auto' when type is known
  • Disable CAPTCHA detection for sites that rarely show CAPTCHAs
  • Monitor result.captcha.detected rates to identify which sites need CAPTCHA solving

Performance Impact​

CAPTCHA solving affects render time:

ModeDetection OverheadSolving Time (if present)Total Impact
disabled0msN/A0ms
auto~100-200ms2-20s (type-dependent)100ms-20s
Specific type~60ms2-20s (type-dependent)60ms-20s

Recommendations:

  • Use disabled by default for unknown sites (two-step approach)
  • Use specific types when CAPTCHA type is known (faster than auto)
  • Combine with aggressive caching to minimize re-renders

Need Help?​