Solve Cloudflare Turnstile With a Proxy: TurnstileTask Explained

Most Cloudflare Turnstile tasks do not need a proxy: ZeroCaptcha solves them from its own network, and the token works when you submit it. Some sites are stricter. They may serve the widget only to certain regions, or check that the token was earned from a network that looks like the visitor’s. For those, TurnstileTask solves through a proxy you provide. This guide shows when to use it, how to pass the proxy in each format, and what can go wrong.

Proxyless first

TurnstileTaskProxyless needs only the page and its sitekey. It is simpler, it has no proxy to fail, and it is the right default. Switch to TurnstileTask only when proxyless tokens are rejected by the site, or the page is not reachable from outside a region. Both task types are on the pricing page, each with its own price per 1,000 solved tasks.

Passing a proxy in createTask

The compatible format takes the proxy two ways. As separate fields, the way many clients send them:

{
  "clientKey": "zc_live_…",
  "task": {
    "type": "TurnstileTask",
    "websiteURL": "https://shop.example.com/login",
    "websiteKey": "0x4AAAAAAAB1cD2eF3gH4iJ5",
    "metadata": { "action": "login", "cdata": "session-7f3a9c2e" },
    "proxyType": "http",
    "proxyAddress": "proxy.example.net",
    "proxyPort": 8080,
    "proxyLogin": "user",
    "proxyPassword": "secret"
  }
}

Or as one URL in proxy:

{
  "clientKey": "zc_live_…",
  "task": {
    "type": "TurnstileTask",
    "websiteURL": "https://shop.example.com/login",
    "websiteKey": "0x4AAAAAAAB1cD2eF3gH4iJ5",
    "metadata": { "action": "login", "cdata": "session-7f3a9c2e" },
    "proxy": "http://user:secret@proxy.example.net:8080"
  }
}

When both are present, proxy wins. proxyType is http, the default, or https, in any case. proxyPort may be a number or a string of digits. The alias AntiTurnstileTask works the same way as TurnstileTask. A proxy changes nothing else about the task: metadata still carries the widget’s data-action and data-cdata (or the action and cData options of turnstile.render()), and any the widget does not set are left out.

Passing a proxy in in.php

The 2Captcha format takes proxy as login:password@host:port or host:port, and proxytype as HTTP, the default, or HTTPS:

# action and data are the widget's data-action and data-cdata (or turnstile.render()'s action and
# cData options); leave out any the widget does not set.
curl -H "Idempotency-Key: $(uuidgen)" \
  "$ZEROCAPTCHA_API/in.php?key=$ZEROCAPTCHA_KEY&method=turnstile&sitekey=0x4AAAAAAAB1cD2eF3gH4iJ5&pageurl=https%3A%2F%2Fshop.example.com%2Flogin&action=login&data=session-7f3a9c2e&proxy=user%3Asecret%40proxy.example.net%3A8080&proxytype=HTTP&json=1"

A malformed proxy, a SOCKS proxy or one that is not public is answered with ERROR_PROXY_FORMAT. See the 2Captcha format.

Passing a proxy in REST

POST /v1/tasks takes the proxy as a URL, such as http://user:secret@proxy.example.net:8080; the Tasks API reference documents the field and its limits.

What the proxy must be

• HTTP or HTTPS. SOCKS4 and SOCKS5 are not supported yet.
• Public. A proxy on a private or reserved address, such as 127.0.0.1 or 10.0.0.0/8, cannot be used. It is refused when you create the task, or, if its name resolves to such an address only when the task runs, the task fails without a charge.
• Working from outside your network. The solver connects to it from ZeroCaptcha’s servers, so an address that only works inside your office or VPC fails.
• Stable for the length of a task. A rotating proxy that changes its exit address mid-task can make the solve fail.

When the proxy fails

A task whose proxy does not work cannot be solved. It ends failed, its hold goes back to your balance at once, and nothing is charged. A proxy that answers badly or not at all makes every solve attempt fail, so the task ends with ERROR_CAPTCHA_UNSOLVABLE. A proxy whose name does not resolve to a public address when the task runs ends it with ERROR_PROXY_NOT_ALLOWED, which res.php reports as ERROR_BAD_PROXY. Refused requests, such as a proxy in the wrong format, never create a task at all. Captcha API error codes lists the outcomes and their costs.

Keep the token on the same network

When you solve through a proxy because the site checks the network, submit the token through the same proxy too. A token earned from one address and submitted from another may be rejected by a strict site, and a Turnstile token works once, so a rejected submission needs a new task.

Proxy credentials

Your proxy’s username and password travel with the task so the solver can use them. ZeroCaptcha never logs the proxy, and deletes it when the task finishes. Even so, use credentials made for this purpose, which you can rotate, rather than an account’s main password.

Language samples

The Cloudflare Turnstile solver page shows complete programs in Python, Node.js, Go, PHP, Java, C# and curl. Add the proxy fields above to the task, change the type to TurnstileTask, and the rest of the code stays the same.