---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/stealth/captcha-solving
markdown_url: https://steel.dev/docs/stealth/captcha-solving.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: CAPTCHA solving
description: Let Steel solve CAPTCHAs as they appear, or have it detect them and solve them only when you call the CAPTCHA endpoints.
summary: Let Steel solve CAPTCHAs as they appear, or have it detect them and solve them only when you call the CAPTCHA endpoints.
type: how-to
reviewed: 2026-11-12
prerequisites:
  - https://steel.dev/docs/stealth.md
related:
  - https://steel.dev/docs/stealth/get-past-bot-detection.md
  - https://steel.dev/docs/stealth/proxies.md
  - https://steel.dev/docs/stealth/dedicated-ips.md
  - https://steel.dev/docs/stealth/fingerprints.md
  - https://steel.dev/docs/stealth/stealth-browser.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# CAPTCHA solving

CAPTCHA solving finds the CAPTCHAs on a session's pages and solves them, so that your code or agent can continue. Turn it on when a site shows a challenge that your task cannot pass alone. [What each plan includes](https://steel.dev/docs/platform/pricing#what-each-plan-includes) shows which plans have it.

Steel solves reCAPTCHA v2 and v3, hCaptcha, Cloudflare Turnstile, image-to-text CAPTCHAs and sliders. It does not solve DataDome, Imperva, Amazon WAF or FunCAPTCHA challenges, and the [CAPTCHA status](https://steel.dev/docs/stealth/captcha-solving#check-the-status) does not show them. No solver works every time, so check the result in your code.

## Before you begin

Put your Steel API key in the `STEEL_API_KEY` environment variable. Then install the Steel SDK and Playwright.

**TypeScript**

```sh
npm install steel-sdk playwright
```

**Python**

```sh
python3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwright
```

In Go and Rust, install only the SDK, as the [Go](https://steel.dev/docs/reference/sdks/go#install) and [Rust](https://steel.dev/docs/reference/sdks/rust#install) SDK pages show. The code that drives the browser uses Playwright, so it is in TypeScript and Python only.

## Solve CAPTCHAs automatically

Set `solveCaptcha` to `true` when you create the session. Steel then solves each CAPTCHA as soon as it detects it, and your code makes no other call. The default is `false`.

Solving takes time, and the time depends on the CAPTCHA and the site. Wait for the solve to finish before you act on the page. This program opens a page with a reCAPTCHA, asks for the [CAPTCHA status](https://steel.dev/docs/stealth/captcha-solving#check-the-status) every 3 seconds until each CAPTCHA has a final status, and prints each CAPTCHA's type and status.

**TypeScript**

```ts file=captcha.mts
import Steel from "steel-sdk";
import { chromium } from "playwright";

type Task = { id: string; type: string; status: string };

const finished = new Set(["solved", "validation_failed", "failed_to_detect", "failed_to_solve"]);

const client = new Steel();

async function waitForCaptchas(sessionId: string) {
  for (let attempt = 0; attempt < 20; attempt++) {
    await new Promise((resolve) => setTimeout(resolve, 3000));
    const pages = await client.sessions.captchas.status(sessionId);
    const tasks = pages.flatMap((state) => state.tasks as Task[]);
    if (tasks.length > 0 && tasks.every((task) => finished.has(task.status))) {
      return tasks;
    }
  }
  throw new Error("The CAPTCHAs did not finish within 60 seconds.");
}

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

try {
  const browser = await chromium.connectOverCDP(session.websocketUrl);
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  await page.goto("https://www.google.com/recaptcha/api2/demo");
  for (const task of await waitForCaptchas(session.id)) {
    console.log(task.type, task.status);
  }
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}
```

**Python**

```python file=captcha.py
import time

from playwright.sync_api import sync_playwright
from steel import Steel

FINISHED = {"solved", "validation_failed", "failed_to_detect", "failed_to_solve"}

client = Steel()


def wait_for_captchas(session_id):
    for _ in range(20):
        time.sleep(3)
        pages = client.sessions.captchas.status(session_id)
        tasks = [task for state in pages for task in state.tasks]
        if tasks and all(task["status"] in FINISHED for task in tasks):
            return tasks
    raise RuntimeError("The CAPTCHAs did not finish within 60 seconds.")


session = client.sessions.create(solve_captcha=True)

try:
    with sync_playwright() as playwright:
        browser = playwright.chromium.connect_over_cdp(session.websocket_url)
        context = browser.contexts[0]
        page = context.pages[0] if context.pages else context.new_page()
        page.goto("https://www.google.com/recaptcha/api2/demo")
        for task in wait_for_captchas(session.id):
            print(task["type"], task["status"])
        browser.close()
finally:
    client.sessions.release(session.id)
```

Run the program:

**TypeScript**

```sh
npx tsx captcha.mts
```

**Python**

```sh
python captcha.py
```

The program prints the CAPTCHA's type and final status.

```text nocopy
recaptchaV2 solved
```

To get fewer CAPTCHAs in the first place, use a [Steel proxy](https://steel.dev/docs/stealth/proxies) and keep the [fingerprint](https://steel.dev/docs/stealth/fingerprints) that Steel gives each session.

## Solve on request

To decide yourself which CAPTCHAs to solve, keep `solveCaptcha` at `true` and set `autoCaptchaSolving` to `false` in `stealthConfig`. Steel detects CAPTCHAs but waits for your call before it solves one.

**TypeScript**

```ts
const session = await client.sessions.create({
  solveCaptcha: true,
  stealthConfig: { autoCaptchaSolving: false },
});
```

**Python**

```python
session = client.sessions.create(
    solve_captcha=True,
    stealth_config={"auto_captcha_solving": False},
)
```

**Go**

```go
session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	SolveCaptcha: steel.F(true),
	StealthConfig: steel.F(steel.SessionNewParamsStealthConfig{
		AutoCaptchaSolving: steel.F(false),
	}),
})
if err != nil {
	return err
}
```

**Rust**

```rust
let session = client
    .sessions()
    .create(steel_rs::SessionCreateParams {
        solve_captcha: Some(true),
        stealth_config: Some(steel_rs::SessionCreateParamsStealthConfig {
            auto_captcha_solving: Some(false),
            ..Default::default()
        }),
        ..Default::default()
    })
    .await?;
```

Then call the solve endpoint. With no options, it solves every CAPTCHA that Steel detected in the session. To solve fewer, pass one of these values from the [status](https://steel.dev/docs/stealth/captcha-solving#check-the-status):

- `taskId`: a task's `id`, to solve that CAPTCHA only.
- `pageId`: a page's `pageId`, to solve every CAPTCHA on that page.
- `url`: a page's `url`, to solve every CAPTCHA on that page.

This code solves each task whose status is `detected`:

**TypeScript**

```ts
const pages = await client.sessions.captchas.status(session.id);
for (const state of pages) {
  for (const task of state.tasks as Task[]) {
    if (task.status === "detected") {
      await client.sessions.captchas.solve(session.id, { taskId: task.id });
    }
  }
}
```

**Python**

```python
pages = client.sessions.captchas.status(session.id)
for state in pages:
    for task in state.tasks:
        if task["status"] == "detected":
            client.sessions.captchas.solve(session.id, task_id=task["id"])
```

**Go**

```go
pages, err := client.Sessions.Captchas.Status(ctx, session.ID)
if err != nil {
	return err
}
for _, state := range *pages {
	for _, item := range state.Tasks {
		task, _ := item.(map[string]any)
		if task["status"] == "detected" {
			id, _ := task["id"].(string)
			_, err = client.Sessions.Captchas.Solve(ctx, session.ID, steel.SessionCaptchaSolveParams{
				TaskID: steel.F(id),
			})
			if err != nil {
				return err
			}
		}
	}
}
```

**Rust**

```rust
let pages = client.sessions().captchas().status(&session.id).await?;
for state in pages {
    for task in state.tasks {
        if task["status"] == "detected" {
            client
                .sessions()
                .captchas()
                .solve(
                    &session.id,
                    steel_rs::SessionCaptchaSolveParams {
                        task_id: task["id"].as_str().map(str::to_owned),
                        ..Default::default()
                    },
                )
                .await?;
        }
    }
}
```

The endpoint starts solving and returns at once. To know when the CAPTCHA is solved, read the status again. With no options, the `message` is `Solve triggered for all captchas`. With a `taskId`, `pageId` or `url`, the response is this one:

```json nocopy
{"success": true, "message": "Captcha solve triggered"}
```

The CAPTCHA endpoints need a session that you created with `solveCaptcha: true`. In a session without it, the status is an empty list, and the solve endpoints return `success` but solve nothing.

## Solve an image CAPTCHA

An image CAPTCHA shows distorted characters in an image and asks you to type them. To solve one, give Steel two XPath expressions: `imageXPath` for the image and `inputXPath` for the field that takes the answer. Add `url` if the CAPTCHA is not on the current page.

**TypeScript**

```ts
const result = await client.sessions.captchas.solveImage(session.id, {
  imageXPath: '//img[@id="captcha-image"]',
  inputXPath: '//input[@name="captcha"]',
});
console.log(result);
```

**Python**

```python
result = client.sessions.captchas.solve_image(
    session.id,
    image_x_path='//img[@id="captcha-image"]',
    input_x_path='//input[@name="captcha"]',
)
print(result)
```

**Go**

```go
import "encoding/json"

result, err := client.Sessions.Captchas.SolveImage(ctx, session.ID, steel.SessionCaptchaSolveImageParams{
	ImageXPath: steel.F(`//img[@id="captcha-image"]`),
	InputXPath: steel.F(`//input[@name="captcha"]`),
})
if err != nil {
	return err
}
out, err := json.MarshalIndent(result, "", "  ")
if err != nil {
	return err
}
fmt.Println(string(out))
```

**Rust**

```rust
let result = client
    .sessions()
    .captchas()
    .solve_image(
        &session.id,
        steel_rs::SessionCaptchaSolveImageParams::new(
            r#"//img[@id="captcha-image"]"#.to_owned(),
            r#"//input[@name="captcha"]"#.to_owned(),
        ),
    )
    .await?;
println!("{}", serde_json::to_string_pretty(&result)?);
```

In Rust, this code needs `cargo add serde_json`.

Steel accepts the request, then reads the image and types the answer into the field.

```json nocopy
{"success": true, "message": "Image captcha solve request sent"}
```

## Check the status

The status endpoint returns one item for each page of the session that Steel watches for CAPTCHAs. Use it to wait for a solve, as the program in [Solve CAPTCHAs automatically](https://steel.dev/docs/stealth/captcha-solving#solve-captchas-automatically) does, or to find the tasks to solve on request.

**TypeScript**

```ts
const pages = await client.sessions.captchas.status(session.id);
console.log(JSON.stringify(pages, null, 2));
```

**Python**

```python
pages = client.sessions.captchas.status(session.id)
print([state.to_dict() for state in pages])
```

**Go**

```go
import "encoding/json"

pages, err := client.Sessions.Captchas.Status(ctx, session.ID)
if err != nil {
	return err
}
out, err := json.MarshalIndent(pages, "", "  ")
if err != nil {
	return err
}
fmt.Println(string(out))
```

**Rust**

```rust
let pages = client.sessions().captchas().status(&session.id).await?;
println!("{}", serde_json::to_string_pretty(&pages)?);
```

Each item has the page's `pageId` and `url`, and a list of `tasks`, one for each CAPTCHA. The item's `isSolvingCaptcha` is `true` while Steel is solving a CAPTCHA on the page. This example shows a page with one solved reCAPTCHA. The IDs and times in your response differ, and a task can have more fields.

```json nocopy
[
  {
    "pageId": "9DB03EF6A157B0C8BC1CD42BB1ADDD0C",
    "url": "https://www.google.com/recaptcha/api2/demo",
    "isSolvingCaptcha": false,
    "tasks": [
      {
        "id": "recaptchaV2-0-content-1794301919874-0s8x6a2ym",
        "pageIndex": 0,
        "pageId": "9DB03EF6A157B0C8BC1CD42BB1ADDD0C",
        "url": "https://www.google.com/recaptcha/api2/demo",
        "status": "solved",
        "type": "recaptchaV2",
        "created": 1794301921412,
        "solveTime": 1794301940187,
        "detectionTime": 1794301921413,
        "totalDuration": 18775
      }
    ],
    "created": 1794301921409,
    "lastUpdated": 1794301940195
  }
]
```

A task's `type` is `recaptchaV2`, `recaptchaV3`, `hcaptcha`, `hcaptchaClick`, `turnstile`, `image_to_text`, `slider` or `unknown`. Steel can add types, so handle a value that you do not know. A task's `status` is one of these:

| Status | Meaning |
| - | - |
| `undetected` | Steel has not detected the CAPTCHA. |
| `detected` | Steel detected the CAPTCHA and has not started to solve it. |
| `solving` | Steel is solving the CAPTCHA. |
| `validating` | Steel submitted the answer and is checking that the page accepts it. |
| `solved` | The CAPTCHA is solved. |
| `validation_failed` | The page did not accept the answer. |
| `failed_to_detect` | The detection failed. |
| `failed_to_solve` | The solving failed. |

The final statuses are `solved`, `validation_failed`, `failed_to_detect` and `failed_to_solve`. When a task is solved, `totalDuration` is the time in milliseconds from detection to the solve. Measure it on your own sites, and set your sessions' [timeouts](https://steel.dev/docs/sessions/timeouts) and your waits above the values that you see.

## Check that it worked

Read the [CAPTCHA status](https://steel.dev/docs/stealth/captcha-solving#check-the-status) after the page loads. Each CAPTCHA that Steel solved has a task with the status `solved`, as the program's output `recaptchaV2 solved` shows. A solved CAPTCHA does not prove that the site let the session through, so also wait for an element of the page that comes after the CAPTCHA. After the session ends, its signals can include `captcha_encountered` even when Steel solved the CAPTCHA, because that signal only records that Steel saw one.

## Plans and pricing

Steel bills each CAPTCHA that it solves, in addition to the session's browser time. [Pricing](https://steel.dev/docs/platform/pricing) has the rate of each plan.

## Troubleshooting

### A CAPTCHA ends in `failed_to_solve`

**Cause:** The solver did not find an answer that the page accepted. Steel also does not solve custom CAPTCHAs that a site builds itself.

**Fix:** Load the page again, or call the solve endpoint again with the `taskId`. For an image CAPTCHA, use the [image solve](https://steel.dev/docs/stealth/captcha-solving#solve-an-image-captcha). Route the session through a [Steel proxy](https://steel.dev/docs/stealth/proxies), so that the site shows fewer challenges. If the challenge is of a kind that Steel does not solve, [hand control to a human](https://steel.dev/docs/observability/hand-control-to-a-human).

**Verify:** Read the status again. The task is `solved`.

### The page stays blocked after the CAPTCHA

**Cause:** The site blocks the browser for reasons other than the CAPTCHA, such as the browser's IP address or behavior. After the session ends, its [signals](https://steel.dev/docs/observability/signals) include `bot_detection_triggered`.

**Fix:** Use a [Steel proxy](https://steel.dev/docs/stealth/proxies) or a [dedicated IP](https://steel.dev/docs/stealth/dedicated-ips), and turn on [human-like input](https://steel.dev/docs/stealth/fingerprints#make-input-human-like). [Get past bot detection](https://steel.dev/docs/stealth/get-past-bot-detection) compares the options.

**Verify:** Run the task again. After the session ends, its signals do not include `bot_detection_triggered`.

### `deposit_required`

On Launch, CAPTCHA solving needs a verified account. You verify it once, with $10 of paid credits, as [Verify a Launch account](https://steel.dev/docs/platform/pricing#verify-a-launch-account) explains. To continue without CAPTCHA solving, remove `solveCaptcha`. [Errors](https://steel.dev/docs/reference/errors#deposit-required) lists the messages.

### `plan_feature_unavailable`

The legacy Hobby plan does not include CAPTCHA solving. Remove `solveCaptcha`, or move to a current plan. [Errors](https://steel.dev/docs/reference/errors#plan-feature-unavailable) lists the messages.

### Could not start CAPTCHA solving

```json nocopy
{
  "error": "Bad Request",
  "message": "Could not start CAPTCHA solving. Check that the session is live and that solveCaptcha was enabled, then retry.",
  "retryable": false,
  "linkToDocs": "https://docs.steel.dev/overview/captchas-api/overview"
}
```

**Cause:** Steel could not reach the session's browser to start the solve, for example because of a network error or a timeout. The message names two other checks, but neither one causes this error. A session that has ended gets `404` with the message `Session not found`. A session without `solveCaptcha` gets `success` and solves nothing.

**Fix:** Send the same call again after a few seconds. The response has `retryable: false`, but the cause can be temporary. If the call keeps failing while the session is `live`, release the session, create a new one, and contact [Support](https://steel.dev/docs/support) with the session ID.

**Verify:** The solve call returns `{"success": true}`.

## Next steps

- [Get past bot detection](https://steel.dev/docs/stealth/get-past-bot-detection): Choose a setup for a site that still blocks the session after the CAPTCHA.
- [Signals](https://steel.dev/docs/observability/signals): See which sessions met a CAPTCHA, and whether Steel solved it.
- [What is a CAPTCHA solver](https://steel.dev/blog/what-is-a-captcha-solver): Read how CAPTCHA solvers work, which CAPTCHAs Steel handles, and the limits to plan for.
