# Captcha Solving
URL: /overview/stealth/captcha-solving

---
title: Captcha Solving
sidebarTitle: Captcha Solving
description: CAPTCHA solving is one of Steel's advanced capabilities that helps AI agents and automation tools navigate the modern web more effectively. This document explains how our CAPTCHA solving system works, what types of CAPTCHAs we support, and best practices for implementation.
full: true
llm: true
---

### How Steel Handles CAPTCHAs

Steel takes a two-pronged approach to dealing with CAPTCHAs:

1.  **Prevention First**: Our sophisticated browser fingerprinting and anti-detection systems often prevent CAPTCHAs from appearing in the first place. We maintain realistic browser profiles that make your automated sessions appear more human-like, reducing the likelihood of triggering CAPTCHA challenges.

2.  **Automatic Solving**: When CAPTCHAs do appear, our automatic solving system kicks in to handle them transparently, allowing your automation to continue without interruption.


### Supported CAPTCHA Types

Currently, Steel's auto-solver supports these CAPTCHA services:

✅ **Currently Supported**:

*   ReCAPTCHA v2 / v3

*   Cloudflare Turnstile

*   ImageToText CAPTCHAs

*   Amazon AWS WAF


🔜 **Coming Soon**:

*   GeeTest v3/v4


❌ **Not Currently Supported**:

*   Custom implementation CAPTCHAs

*   Enterprise-specific CAPTCHA systems

*   FunCAPTCHA

*   Other specialized CAPTCHA types


### How CAPTCHA Solving Works

When you enable CAPTCHA solving in your Steel session, here's what happens behind the scenes:

1.  **Detection**: Our system continuously monitors the page for CAPTCHA elements using multiple detection methods:

    *   DOM structure analysis

    *   Known CAPTCHA iframe patterns

    *   Common CAPTCHA API endpoints

    *   Visual element detection

2.  **State Management**: CAPTCHA states are tracked per page with real-time updates

3.  **Classification**: Once detected, the system identifies the specific type of CAPTCHA and routes it to the appropriate solver.

4.  **Solving**: CAPTCHAs are then solved by us using various methods:

    *   Machine learning models

    *   Third-party solving services

    *   Browser automation techniques

    *   Token manipulation (when applicable)

5.  **Verification**: The system verifies that the CAPTCHA was successfully solved before allowing the session to continue.


### Session Configuration

To enable autosolving, simply set `solveCaptcha: true` when creating a session.

<CodeTabs storage="languageSwitcher">

```typescript !! Typescript -wcn
import Steel from 'steel-sdk';

const client = new Steel();

const session = await client.sessions.create({
  solveCaptcha: true
});
```

```python !! Python -wcn
from steel import Steel

client = Steel()
session = client.sessions.create(
    solve_captcha=True
)
```
</CodeTabs>

To detect CAPTCHAs without automatically solving them, disable `autoCaptchaSolving` in the stealth config:

<CodeTabs storage="languageSwitcher">

```typescript !! Typescript -wcn
const session = await client.sessions.create({
  solveCaptcha: true,
  stealthConfig: {
    autoCaptchaSolving: false
  }
});
```

```python !! Python -wcn
session = client.sessions.create(
    solve_captcha=True,
    stealth_config={
        "autoCaptchaSolving": False
    }
)
```
</CodeTabs>

### Manual Solving

If auto-solving is disabled, use the solve endpoint to trigger solving. You can solve all detected CAPTCHAs or target specific ones.

The `taskId`, `url`, and `pageId` required for targeting specific CAPTCHAs can be retrieved from the [CAPTCHA status response](/overview/captchas-api/overview#getting-captcha-status). When using `taskId`, use the value from the task's `id` field.

<CodeTabs storage="languageSwitcher">

```typescript !! Typescript -wcn
// Solve all detected CAPTCHAs
await client.sessions.captchas.solve('sessionId');

// Solve specific task
await client.sessions.captchas.solve('sessionId', { taskId: 'task_123' });

// Solve by URL
await client.sessions.captchas.solve('sessionId', { url: 'https://example.com' });

// Solve by Page ID
await client.sessions.captchas.solve('sessionId', { pageId: 'page_123' });
```

```python !! Python -wcn
# Solve all detected CAPTCHAs
client.sessions.captchas.solve("sessionId")

# Solve specific task
client.sessions.captchas.solve("sessionId", task_id="task_123")

# Solve by URL
client.sessions.captchas.solve("sessionId", url="https://example.com")

# Solve by Page ID
client.sessions.captchas.solve("sessionId", page_id="page_123")
```
</CodeTabs>

### Best Practices for Implementation

#### 1\. Implement Proper Waiting

When navigating to pages that might contain CAPTCHAs, it's important to implement proper waiting strategies:

<CodeTabs storage="languageSwitcher">

```typescript !! Typescript -wcn
// Typescript example using Puppeteer
await page.waitForNetworkIdle();  // Wait for network activity to settle
await page.waitForTimeout(2000);  // Additional safety buffer
```

```python !! Python -wcn
# Python example using Playwright
await page.wait_for_load_state('networkidle')  # Wait for network activity to settle
await page.wait_for_timeout(2000)  # Additional safety buffer
```
</CodeTabs>

#### 2. Detecting CAPTCHA Presence

You can detect CAPTCHA presence using these selectors:

```typescript Typescript -wcn
// Common CAPTCHA selectors
const captchaSelectors = [
    'iframe[src*="recaptcha"]',
    '#captcha-box',
    '[class*="captcha"]'
];
```


### Important Considerations

1.  **Plan Availability**: CAPTCHA solving is only available on Developer, Startup, and Enterprise plans. It is not included in the free tier.

2.  **Success Rates**: While our system has high success rates, CAPTCHA solving is not guaranteed to work 100% of the time. Always implement proper error handling.

3.  **Timing**: CAPTCHA solving can add latency to your automation. Account for this in your timeouts and waiting strategies.

4.  **Rate Limits**: Even with successful CAPTCHA solving, respect the target site's rate limits and terms of service.


### Common Issues and Solutions

1.  **Timeout Issues**

    *   Increase your session timeout when working with CAPTCHA-heavy sites

    *   Implement exponential backoff for retries

2.  **Detection Issues**

    *   Use Steel's built-in stealth profiles

    *   Implement natural delays between actions

    *   Rotate IP addresses using Steel's proxy features

3.  **Solving Failures**

    *   Implement proper error handling

    *   Have fallback strategies ready

    *   Consider implementing manual solving as a last resort


### Best Practices for Avoiding CAPTCHAs

1.  **Use Steel's Fingerprinting**: Our automatic fingerprinting often helps bypass avoidable CAPTCHAs entirely by making your sessions appear more human-like.

2.  **Session Management**:

    *   Reuse successful sessions when possible

    *   Maintain cookies and session data

    *   Use Steel's session persistence features

3.  **Request Patterns**:

    *   Implement natural delays between actions

    *   Vary your request patterns

    *   Avoid rapid, repetitive actions


### Looking Forward

Steel is continuously improving its CAPTCHA handling capabilities. We regularly update our solving mechanisms to handle new CAPTCHA variants and improve success rates for existing ones.

Stay updated with our documentation for the latest information about supported CAPTCHA types and best practices.

:::callout
type: help
### Need help building with captcha solving?
Reach out to us on the <span className="font-bold">#help</span> channel on [Discord](https://discord.gg/steel-dev) under the ⭐ community section.
:::

### FAQ

### How does Steel handle CAPTCHAs?

With a two-pronged approach: browser fingerprinting and anti-detection systems prevent many CAPTCHAs from appearing in the first place, and when one does appear, automatic solving handles it transparently. Enable it by setting `solveCaptcha: true` when creating a session.

### What CAPTCHA types does Steel support?

Steel's auto-solver currently handles reCAPTCHA v2 and v3, hCaptcha, Cloudflare Turnstile, image-to-text, and slider CAPTCHAs. Systems like DataDome, Imperva, Amazon WAF, and FunCAPTCHA are detected and logged but not auto-solved, and custom or enterprise-specific implementations aren't supported.

### Does Steel's CAPTCHA solver work 100% of the time?

No — the system has high success rates but solving is not guaranteed to work 100% of the time, so you should implement proper error handling. Solving can also add latency, so account for it in your timeouts and waiting strategies.

### How can I avoid triggering CAPTCHAs in the first place?

Use Steel's automatic fingerprinting (which often bypasses avoidable CAPTCHAs by making sessions appear more human-like), reuse successful sessions while maintaining cookies, and add natural delays while avoiding rapid, repetitive actions.