Proxy Configuration

Some tasks need to be solved from your IP. For those, include a proxy in the task field (string or object).

{
    "clientKey": "YOUR_API_KEY",
    "task": {
        "type": "ReCaptchaV2Token",
        "websiteURL": "https://example.com",
        "websiteKey": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI",
        "proxy": "http://user:[email protected]:8080"
    }
}

Keep the same IP for the whole solve

A solve is never a single request: the provider loads the page, interacts with the challenge, and fetches the result, all through your proxy. Most CAPTCHA flows additionally check that the IP that solved the challenge is the IP that later submits the form. Both only work when the proxy keeps one IP for the entire solve, so a proxy that rotates its IP on every request will make the solve fail or produce a token the target site rejects.

What works best in practice:

• Use a sticky session (every major rotating-proxy provider offers one): the proxy holds a single IP for a time window. Pick a window of at least 5 minutes so the IP cannot change mid-solve.
• Use one sticky session per solve. Don't share a session across parallel solves, and start a fresh session (fresh IP) for the next one.
• Submit the form through the same session that solved the challenge, so the IPs match.

String formats

Schemes: http, https, socks4, socks5. No scheme defaults to http. Most providers only support http.

Object format

{    "type": "http",    "host": "192.168.1.1",    "port": 8080,    "username": "proxy-user",    "password": "proxy-pass"}

Multiple proxies

task.proxy accepts either a single proxy or an array of proxies. Mix strings and objects freely:

{
    "task": {
        "proxy": [
            "http://user:[email protected]:8080",
            { "type": "http", "host": "5.6.7.8", "port": 8080, "username": "user", "password": "pass" }
        ]
    }
}

Rotation across attempts

When auto retry or auto fallback is enabled on a proxy task, each attempt consumes the next proxy in the array. Attempt 0 uses index 0, attempt 1 uses index 1, and so on. This avoids re-trying a banned or dead IP into the same failure.

If there are more attempts than proxies, the rotation wraps around to the start of the list, so you never have to size the array for the worst case. Provide as many distinct proxies as you want fresh IPs (up to 100); beyond that, attempts reuse earlier ones.

Because a single proxy would be sent to every attempt, a one-proxy task with retry or fallback enabled is rejected unless you opt in with allowProxyReuse: true. Pass an array to rotate instead:

{
    "task": { "proxy": ["http://user:[email protected]:8080", "http://user:[email protected]:8080"] },
    "settings": { "retry": { "enabled": true, "maxRetries": 1 } }
}

To deliberately reuse a single proxy across every attempt, set allowProxyReuse: true:

{
    "task": { "proxy": "http://user:[email protected]:8080" },
    "settings": {
        "retry": { "enabled": true, "maxRetries": 2 },
        "allowProxyReuse": true
    }
}

Which proxy was used

When a completed task used a proxy, getTaskResult returns it as usedProxy, exactly as you submitted it. With rotation, this is the final attempt's proxy. With settings.statistics enabled, the retry history additionally carries a per-attempt proxyIndex.

{ "usedProxy": { "index": 1, "type": "http", "host": "5.6.7.8", "port": 8080, "username": "user", "password": "pass" } }

Proxy types