Polling

There is no webhook and no long-poll: you create a task and ask for the result until it is ready. The pattern is simple, but the timing choices decide whether your p95 looks like ours.

Cadence

• Wait about 1.5 seconds before the first poll. Nothing resolves faster than that, so an immediate poll is a wasted round trip.
• Then poll every 0.5 seconds. Faster gains you nothing and risks ERROR_RATE_LIMIT; slower adds latency you will see in your own metrics.
• Do not add exponential backoff to a healthy task. Solve times are seconds, not minutes, and backoff turns a 2-second solve into a 4-second one.
• Do back off when you receive ERROR_RATE_LIMIT, and keep the same taskId — the task is still running.

import time, requests

API, KEY = "https://api.captchapi.com", "YOUR_API_KEY"

def solve(task, first_delay=1.5, interval=0.5, timeout=120):
    created = requests.post(f"{API}/createTask",
                            json={"clientKey": KEY, "task": task}).json()
    if created["errorId"] != 0:
        raise RuntimeError(created["errorCode"])

    deadline = time.time() + timeout
    time.sleep(first_delay)

    while time.time() < deadline:
        r = requests.post(f"{API}/getTaskResult",
                          json={"clientKey": KEY,
                                "taskId": created["taskId"]}).json()

        if r.get("status") == "ready":
            return r["solution"]
        if r["errorId"] != 0 and r.get("errorCode") != "ERROR_RATE_LIMIT":
            raise RuntimeError(r["errorCode"])

        time.sleep(interval)

    raise TimeoutError("task did not resolve in time")

Deadlines

Give a task 120 seconds before you abandon it. Turnstile and reCAPTCHA v3 resolve in single-digit seconds; hCaptcha multi-round challenges are the long tail and can reach half a minute. If your own request budget is tighter than that, set a shorter client deadline and treat the overrun as a failure — the task is still refunded on our side when it times out.

Running many at once

Tasks are independent, so create them in parallel and poll each one on its own timer. The default ceiling is 100 in flight per key. Measured on our production VPS, a pool of six browsers completes ten tasks in 12.6 seconds of wall clock — roughly 0.8 solves per second — so throughput scales with our capacity, not with how hard you poll.

Poll every task on its own schedule rather than batching a sweep every few seconds. A shared sweep adds half its interval to the average latency of every task in it.