CAPTCHA solving

Surfsky exposes CAPTCHA commands through a page-level CDP session. Enable anti_captcha when starting the browser, choose a solver for the challenge, and verify the page state after solving.

Enable solving

Add this to the browser start body:

{
  "anti_captcha": {
    "enabled": true,
    "auto_captcha_types": ["turnstile"]
  }
}

Use auto_captcha_types to restrict automatic detection to the types your page needs. It does not restrict an explicit manual Captcha.solve request.

Provider configuration

Setting	Purpose
`enabled`	Enables the CAPTCHA subsystem. Defaults to `false`.
`auto_captcha_types`	Types permitted in automatic mode. Set an explicit list for predictable behavior.

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.

Choose a method

Challenge	Manual `Captcha.solve`	Automatic `Captcha.autoSolve`	Cost	Guide
reCAPTCHA	Yes	Yes	Paid	reCAPTCHA
GeeTest	Yes, v4	Yes, v4	Paid	GeeTest
AWS WAF	Yes	Yes	Paid	AWS WAF
BLS	No	Yes	Paid	BLS
Turnstile	Yes	Yes	Free	Turnstile
PerimeterX	Yes	Yes	Free	PerimeterX
DataDome audio or slider	Yes	Yes	Audio paid, slider free	DataDome
FunCaptcha audio	Yes	Yes	Paid	FunCaptcha
A known click target	Yes	No	Free	Click
Image-to-text	Yes	No	Paid	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={
        "anti_captcha": {
            "enabled": True,
            "auto_captcha_types": ["turnstile"],
        },
        "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, add anti_captcha to its start body, 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. Pass anti_captcha to client.browser() and 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 AntiCaptcha, AsyncSurfsky


async def main():
    captcha = AntiCaptcha(enabled=True, auto_captcha_types=["turnstile"])
    async with AsyncSurfsky() as client:
        async with client.browser(anti_captcha=captcha) 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({
  anti_captcha: { enabled: true, auto_captcha_types: ["turnstile"] },
});
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.

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, Surfsky tries manual detection.
`timeout`	Overall timeout in milliseconds for the manual attempt.
`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. 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. 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", {"type": "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", { type: "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", {"type": "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", { type: "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. type restricts detection to one allowed type. Omit it to detect among the configured auto_captcha_types. Calling autoSolve again replaces the current background loop; 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. 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 is allowed, and the default auto_captcha_types includes paid types. Set your own list to control what is charged.

Troubleshooting

Symptom	Check
Solver is not enabled	Set `anti_captcha.enabled: true` in the browser start request.
Type is not allowed in automatic mode	Include it in `auto_captcha_types` before starting the browser.
No CAPTCHA detected	Inspect the page and frame; wait for the challenge to appear. Only reCAPTCHA, PerimeterX, and AWS WAF are found inside a site’s own iframes.
`status: "started"` but content is still blocked	Observe solve events and wait for the actual page result.
Repeated failures	Check provider configuration, balance, proxy behavior, and 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. Keep provider keys out of logs and source control.

Get started

Connect your tools

Browser sessions

Browser actions

CAPTCHA guides

Debugging

Performance and limits

About Surfsky

CAPTCHA solving

Enable solving

Provider configuration

Choose a method

Connect and solve

With an SDK

Manual solving

Automatic solving

Events

Charges

Troubleshooting

​Enable solving

​Provider configuration

​Choose a method

​Connect and solve

​With an SDK

​Manual solving

​Automatic solving

​Events

​Charges

​Troubleshooting

Enable solving

Provider configuration

Choose a method

Connect and solve

With an SDK

Manual solving

Automatic solving

Events

Charges

Troubleshooting