Docs / Guides

Proxies

Which task types need a proxy, the proxy formats the API accepts, and how to keep exit IP and user agent consistent so solved tokens verify on your side.

Some captcha deployments tie a solution to the IP that earned it: a token or cookie is only useful from the same exit IP, and often with the same user agent. Those types take proxy details in the task. Types that run fine from shared infrastructure accept none.

Proxy mode per task type

Task type	Proxy mode	What the mode means
reCAPTCHA v2	optional	Proxyless, or through a proxy you supply when you send the proxy-capable name.
reCAPTCHA v3	optional	Proxyless, or through a proxy you supply when you send the proxy-capable name.
Cloudflare Turnstile	optional	Proxyless, or through a proxy you supply when you send the proxy-capable name.
Cloudflare Challenge	required	A proxy is required; there is no proxyless variant.
Vercel	required	A proxy is required; there is no proxyless variant.
FriendlyCaptcha	optional	Proxyless, or through a proxy you supply when you send the proxy-capable name.
Altcha	none	Proxyless only; both accepted names work and a proxy is never required.
Prosopo	optional	Proxyless, or through a proxy you supply when you send the proxy-capable name.
CaptchaFox	required	A proxy is required; there is no proxyless variant.
GeeTest	optional	Proxyless, or through a proxy you supply when you send the proxy-capable name.
MTCaptcha	optional	Proxyless, or through a proxy you supply when you send the proxy-capable name.
Akamai	required	A proxy is required; there is no proxyless variant.
DataDome	required	A proxy is required; there is no proxyless variant.
PerimeterX	required	A proxy is required; there is no proxyless variant.

The name you send decides whether a proxy is required for an optional type: the …TaskProxyLess form never needs one, while the proxy-capable …Task form requires proxy details and a request without them is rejected with ERROR_INVALID_REQUEST. Types marked required have no proxyless name at all — sending one answers ERROR_TYPE_NOT_SUPPORTED.

Accepted proxy formats

Send the proxy as a string in task.proxy:

snippet.txt

http://user:[email protected]:8000
socks5://user:[email protected]:1080
user:[email protected]:8000
203.0.113.10:8000

The scheme is http, https, socks4 or socks5; without one, http is assumed. Credentials are optional — a bare host:port is how IP-allowlisted proxies are used. A string with exactly four colon-separated parts is always read as user:password:host:port, with or without a scheme (socks5://user:password:host:port). The order is not detected: some clients send the opposite one (host:port:user:pass), and such a string is not rejected when it happens to parse the other way — for example 203.0.113.10:8000:user:12345 would be taken as user 203.0.113.10, password 8000, host user, port 12345, and the task would be charged while using the wrong proxy. Convert strings in that order, or use the split fields below. Other layouts, such as type:ip:port:user:pass, are rejected with ERROR_INVALID_REQUEST.

Or send the split fields — the explicit form, the safest one to generate, and the recommended one when migrating from a vendor whose string order differs. They are read only when task.proxy is absent or empty:

snippet.json

{
  "proxyType": "http",
  "proxyAddress": "203.0.113.10",
  "proxyPort": 8000,
  "proxyLogin": "user",
  "proxyPassword": "password"
}

proxyAddress and proxyPort are required together; proxyType is one of http, https, socks4 or socks5 (any other value is treated as http), and proxyLogin / proxyPassword are optional. A missing or non-numeric port, or a task.proxy string that cannot be parsed or names an unknown scheme, is rejected with ERROR_INVALID_REQUEST.

Consistency rules

Replay a token or cookie from the same exit IP and with the same userAgent the solution reports. A different IP or user agent is the usual reason a valid-looking solution is refused by the target.
For cookie-producing types, use a sticky proxy session for the whole flow: challenge, solve, and the request that consumes the cookie.
Match the proxy class to what the target accepts. Anti-bot vendors commonly refuse datacenter ranges; choosing a type that runs proxyless avoids the question entirely.
The proxy is part of the task, not a global setting: each createTask that needs one carries its own details.