Skip to content

CAPTCHA solving

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

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 playwright

In 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.

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

Run the program:

npx tsx captcha.mts

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

recaptchaV2 solved

To 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 },
});

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'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:

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

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);

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));

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:

StatusMeaning
undetectedSteel has not detected the CAPTCHA.
detectedSteel detected the CAPTCHA and has not started to solve it.
solvingSteel is solving the CAPTCHA.
validatingSteel submitted the answer and is checking that the page accepts it.
solvedThe CAPTCHA is solved.
validation_failedThe page did not accept the answer.
failed_to_detectThe detection failed.
failed_to_solveThe 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}.

Next steps