CAPTCHA solving

Surfsky exposes CAPTCHA commands through a page-level CDP session. They work in any browser you start, with no setup: choose a solver for the challenge, send the command, and verify the page state after solving.

Choose a method

Some solvers are free. The others are built in but paid separately: each of their solves is charged on top of browser time, as described in Charges. The Cost column below shows which is which.

Challenge	`Captcha.detect`	Manual `Captcha.solve`	Automatic `Captcha.autoSolve`	Cost	Guide
reCAPTCHA	Yes	Yes	Yes	~$0.0002	reCAPTCHA
GeeTest	Yes, v4	Yes, v4	Yes, v4	~$0.0015	GeeTest
AWS WAF	Yes	Yes	Yes	~$0.0015	AWS WAF
BLS	No	No	Yes	Paid	BLS
Turnstile	Yes	Yes	Yes	Free	Turnstile
PerimeterX	Yes	Yes	Yes	Free	PerimeterX
DataDome audio or slider	Yes	Yes	Yes	Audio paid, slider free	DataDome
FunCaptcha audio	Yes	Yes	Yes	Paid	FunCaptcha
A known click target	No	Yes	No	Free	Click
Image-to-text	No	Yes	No	~$0.0003	Image

Support can vary by challenge version and site configuration. Test on your target page and check that the protected content loads.

Connect and solve

This Python example starts a browser, connects Playwright, and attempts a manual Turnstile solve. Install the packages and set your Surfsky credentials:

pip install requests playwright
export TARGET_URL="https://your-site.example/protected-page"

Replace TARGET_URL with the page you are testing. Save as solve.py:

import os
import requests
from playwright.sync_api import sync_playwright

base_url = os.environ["SURFSKY_API_BASE_URL"].rstrip("/")
headers = {"X-Cloud-Api-Token": os.environ["SURFSKY_API_TOKEN"]}
response = requests.post(
    f"{base_url}/profiles/one_time",
    headers=headers,
    json={"browser_settings": {"inactive_kill_timeout": 120}},
    timeout=120,
)
response.raise_for_status()
session = response.json()
try:
    with sync_playwright() as pw:
        browser = pw.chromium.connect_over_cdp(session["ws_url"])
        try:
            context = browser.contexts[0]
            page = context.pages[0] if context.pages else context.new_page()
            cdp = page.context.new_cdp_session(page)
            page.goto(os.environ["TARGET_URL"], wait_until="domcontentloaded")
            result = cdp.send("Captcha.solve", {
                "type": "turnstile",
                "timeout": 60000,
            })
            print(result)
            if result["status"] != "success":
                raise RuntimeError(f"Solve ended with {result['status']}")
            # Add a wait for your site's protected content here.
        finally:
            browser.close()
finally:
    stopped = requests.post(
        f"{base_url}/profiles/{session['internal_uuid']}/stop",
        headers=headers, timeout=120,
    )
    if stopped.status_code != 404:
        stopped.raise_for_status()

Run it:

python solve.py

A successful attempt returns {"status": "success", "type": "turnstile", "solution": "<token>"}. If no challenge is present, the command fails with the CDP error No captcha detected on the page. The final API request stops the browser when the example exits. For JavaScript, start with the Playwright lifecycle and create the CDP session with await page.context().newCDPSession(page). The command parameters are the same.

With an SDK

The Python and TypeScript SDKs start the session and speak CDP themselves. Send the commands with browser.send. Install the Python or TypeScript SDK, set TARGET_URL and your credentials as above, and run:

import asyncio
import os
from surfsky import AsyncSurfsky


async def main():
    async with AsyncSurfsky() as client:
        async with client.browser() as browser:
            await browser.goto(os.environ["TARGET_URL"], wait_until="domcontentloaded")
            result = await browser.send("Captcha.solve", {"type": "turnstile", "timeout": 60000})
            print(result)
            if result["status"] != "success":
                raise RuntimeError(f"Solve ended with {result['status']}")


asyncio.run(main())

import { Surfsky } from "surfsky";

const client = new Surfsky();
const browser = await client.browser();
try {
  await browser.goto(process.env.TARGET_URL, { waitUntil: "domcontentloaded" });
  const result = await browser.send("Captcha.solve", { type: "turnstile", timeout: 60000 });
  console.log(result);
  if (result.status !== "success") throw new Error(`Solve ended with ${result.status}`);
} finally {
  await browser.close();
}

The browser stops when the block exits. browser.send waits 60 seconds for a reply: for a solver whose timeout is longer, such as reCAPTCHA, start the browser with command_timeout=200 in Python (seconds) or commandTimeout: 200_000 in TypeScript (milliseconds). Events arrive through browser.cdp.on(event, handler). The handler gets the event’s fields and the page’s session id.

Detection

Captcha.detect looks at the current page once and says whether a captcha or a challenge page is on it, without solving anything. It needs no solver and is free:

const found = await cdp.send("Captcha.detect");

The reply names what was found:

{
  "detected": true,
  "captcha_type": "turnstile",
  "selector": "iframe:is([src*=\"challenges.cloudflare.com/\"], [src*=\"abuse.cloudflare.com/\"])",
  "challenge_page": "cloudflare"
}

detected says whether a captcha a solver can act on is on the page, captcha_type is its type as Captcha.solve takes it, and selector is the element it was found by. challenge_page names the provider of a challenge page served in place of the one you asked for, cloudflare, datadome or perimeterx, with or without a captcha on it. On a page with neither, every field but detected: false is null. Detection sees open and closed shadow roots, the provider’s own iframe, and a widget inside a site’s own iframe. The same scan is what Captcha.solve without type and Captcha.autoSolve use to find a captcha, and a Captcha.detect call emits Captcha.detectionStarted and Captcha.detectionCompleted.

Manual solving

Captcha.solve waits for one attempt to finish:

const result = await cdp.send("Captcha.solve", {
  type: "turnstile",
  timeout: 60000,
});

Parameter	Meaning
`type`	Solver type. When omitted, detection picks it.
`timeout`	Overall timeout in milliseconds for the manual attempt, 180000 when absent.
`options.selector`	Click solving: required CSS selector or `[x, y]` coordinates of the target. Image-to-text: required CSS selector of the image. Other solvers find the challenge themselves.
`options.input`	Image-to-text: CSS selector of the field to type the answer into.

Pass only the options listed in the selected solver’s guide. Solvers may ignore other fields even when the request accepts them. Results include status and type. Statuses include success, failed, timeout, and not_detected, which means there was nothing to solve, for example a widget that had already passed. On success, solution holds the answer when the solver has one, such as a token or the recognized text. Invalid parameters and detection failures raise CDP errors instead of returning a status object. Captcha.solve can be called right after navigation: a widget that is on the page but not drawn yet is waited for a few seconds. With no widget on the page it fails at once with No captcha detected on the page. A hidden or invisible widget is not a captcha: call Captcha.solve after the step that shows it, such as the form’s submit. A charged solve also returns usage, on failed and timeout too:

{
  "status": "success",
  "type": "recaptcha",
  "usage": {"cost_usd": 0.0004}
}

usage.cost_usd is what the solve was charged.

Automatic solving

Use Captcha.autoSolve to start background detection on the page, with the types to watch in types. Attach event listeners before starting it, then navigate:

cdp.on("Captcha.solveCompleted", lambda event: print("Solve completed:", event))
cdp.on("Captcha.solveFailed", lambda event: print("Solve failed:", event))

await cdp.send("Captcha.autoSolve", {"types": ["turnstile"]})
await page.goto(target_url, wait_until="domcontentloaded")
# Wait for a selector or response that identifies your protected content.

cdp.on("Captcha.solveCompleted", (event) => {
  console.log("Solve completed:", event.type, event.status);
});
cdp.on("Captcha.solveFailed", (event) => {
  console.error("Solve failed:", event.type, event.status ?? event.error);
});

await cdp.send("Captcha.autoSolve", { types: ["turnstile"] });
await page.goto(targetUrl, { waitUntil: "domcontentloaded" });
// Wait for a selector or response that identifies your protected content.

browser.cdp.on("Captcha.solveCompleted", lambda event, _: print("Solve completed:", event))
browser.cdp.on("Captcha.solveFailed", lambda event, _: print("Solve failed:", event))

await browser.send("Captcha.autoSolve", {"types": ["turnstile"]})
await browser.goto(target_url, wait_until="domcontentloaded")
# Wait for a selector or response that identifies your protected content.

browser.cdp.on("Captcha.solveCompleted", (event) => {
  console.log("Solve completed:", event.type, event.status);
});
browser.cdp.on("Captcha.solveFailed", (event) => {
  console.error("Solve failed:", event.type, event.status ?? event.error);
});

await browser.send("Captcha.autoSolve", { types: ["turnstile"] });
await browser.goto(targetUrl, { waitUntil: "domcontentloaded" });
// Wait for a selector or response that identifies your protected content.

The response {"status": "started"} confirms that background solving started. Wait for the expected page content or response to confirm completion, and set a timeout for that wait. types sets which types automatic mode watches:

Without types, the default set applies: recaptcha, geetest, turnstile, perimeterx, datadome and datadome_audio. On DataDome the slider (datadome) goes first; audio takes over after three slider failures in a row.
A list watches only the types in it. aws_waf and funcaptcha are not in the default set: list them to solve them automatically.
[] watches every type except recaptcha, geetest and aws_waf. It still includes the paid DataDome audio and FunCaptcha.

An unknown name fails with Invalid captcha type. types does not restrict a manual Captcha.solve. type restricts detection to one of the watched types; a type outside them fails with is not in types, and a type your account has no automatic solver for fails with is not available for this account, listed or not. Calling autoSolve again replaces the current background loop, types included; disconnecting the CDP client ends it. After three failed solves in a row of one type, the loop stops solving that type, sends a Captcha.solveFailed event with error, and keeps solving the others; with type set, the loop ends. A challenge that has already passed is skipped without events.

Events

Event	When it is emitted
`Captcha.detectionStarted`	Detection begins.
`Captcha.detectionCompleted`	Detection finishes.
`Captcha.solveStarted`	A solve attempt begins.
`Captcha.solveCompleted`	An attempt returns success.
`Captcha.solveFailed`	An attempt fails, times out, or raises an error.

Payload fields depend on the event. Captcha.solveCompleted and Captcha.solveFailed carry the same fields as a Captcha.solve result, usage included. A solve that ended in an error sends error and the type when known.

Charges

A paid solve is charged whatever its outcome, failed and timeout included: how hard a challenge gets depends mostly on the proxy and the browser session. The charge equals the solve’s usage.cost_usd and is recorded against the browser session. The amounts in the Cost column are typical for one solve, not fixed prices. Nothing is charged when the challenge passes on its own, such as a reCAPTCHA checkbox that passes without a challenge or a GeeTest widget that passes on its button. Automatic mode solves, and charges for, every type it watches, and the default set includes paid types. Pass your own types to control what is charged.

Troubleshooting

Symptom	Check
`type` is not in `types`	Add it to `types` on `Captcha.autoSolve`.
`type` is not available for this account	Your account has no automatic solver for that type, and `types` does not change that. The type’s guide says what it needs.
No CAPTCHA detected	Inspect the page with `Captcha.detect`; wait for the challenge to appear.
`status: "started"` but content is still blocked	Observe solve events and wait for the actual page result.
Repeated failures	Check proxy behavior and the current challenge type.
Solver succeeds but data is missing	The page may still need navigation, form submission, or another wait.

Use DevTools or Screencast to observe one attempt before increasing concurrency.

Get started

Connect your tools

Browser sessions

Browser actions

CAPTCHA guides

Debugging

Performance and limits

About Surfsky

CAPTCHA solving

Choose a method

Connect and solve

With an SDK

Detection

Manual solving

Automatic solving

Events

Charges

Troubleshooting

​Choose a method

​Connect and solve

​With an SDK

​Detection

​Manual solving

​Automatic solving

​Events

​Charges

​Troubleshooting

Choose a method

Connect and solve

With an SDK

Detection

Manual solving

Automatic solving

Events

Charges

Troubleshooting