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 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 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.
npm install steel-sdk playwrightpython3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwrightIn Go and Rust, install only the SDK, as the Go and Rust 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 every 3 seconds until each CAPTCHA has a final status, and prints each CAPTCHA's type and status.
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);
}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:
npx tsx captcha.mtspython captcha.pyThe program prints the CAPTCHA's type and final status.
recaptchaV2 solvedTo get fewer CAPTCHAs in the first place, use a Steel proxy and keep the fingerprint 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.
const session = await client.sessions.create({
solveCaptcha: true,
stealthConfig: { autoCaptchaSolving: false },
});session = client.sessions.create(
solve_captcha=True,
stealth_config={"auto_captcha_solving": False},
)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
}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:
taskId: a task'sid, to solve that CAPTCHA only.pageId: a page'spageId, to solve every CAPTCHA on that page.url: a page'surl, to solve every CAPTCHA on that page.
This code solves each task whose status is detected:
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 });
}
}
}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"])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
}
}
}
}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:
{"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.
const result = await client.sessions.captchas.solveImage(session.id, {
imageXPath: '//img[@id="captcha-image"]',
inputXPath: '//input[@name="captcha"]',
});
console.log(result);result = client.sessions.captchas.solve_image(
session.id,
image_x_path='//img[@id="captcha-image"]',
input_x_path='//input[@name="captcha"]',
)
print(result)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))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.
{"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 does, or to find the tasks to solve on request.
const pages = await client.sessions.captchas.status(session.id);
console.log(JSON.stringify(pages, null, 2));pages = client.sessions.captchas.status(session.id)
print([state.to_dict() for state in pages])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))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.
[
{
"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 and your waits above the values that you see.
Check that it worked
Read the CAPTCHA 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 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. Route the session through a Steel proxy, so that the site shows fewer challenges. If the challenge is of a kind that Steel does not solve, 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 include bot_detection_triggered.
Fix: Use a Steel proxy or a dedicated IP, and turn on human-like input. 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 explains. To continue without CAPTCHA solving, remove solveCaptcha. Errors lists the messages.
plan_feature_unavailable
The legacy Hobby plan does not include CAPTCHA solving. Remove solveCaptcha, or move to a current plan. Errors lists the messages.
Could not start CAPTCHA solving
{
"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 with the session ID.
Verify: The solve call returns {"success": true}.