Proxy Configuration
How to pass a proxy for tasks that require IP matching.
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"
}
}String formats
Schemes: http, https, socks4, socks5. No scheme defaults to http. Most providers only support http.
| Format | Example |
|---|---|
scheme://user:pass@host:port | http://admin:[email protected]:8080 |
scheme://user:pass:host:port | http://admin:secret:1.2.3.4:8080 |
scheme://host:port | socks5://1.2.3.4:1080 |
user:pass@host:port | admin:[email protected]:8080 |
user:pass:host:port | admin:secret:1.2.3.4:8080 |
host:port | 1.2.3.4:8080 |
| IPv6 | http://user:pass@[2001:db8::1]:8080 |
Passwords containing `:` and IPv6
The colon-separated user:pass:host:port form can't disambiguate passwords with : and does not support IPv6
addresses (the :s in the address collide). For passwords with colons or IPv6 hosts, use the @-separated form or
a full URL.
Object format
| Field | Type | Required | Description |
|---|---|---|---|
type* | Yes | Proxy protocol: http, https, socks4, or socks5. Example: | |
host* | string | Yes | Proxy server hostname or IP address. Example: |
port* | unknown | Yes | Port the proxy listens on (1 - 65535). Example: |
username | string | No | Username for proxy authentication (if required). Example: proxy-user. Example: |
password | string | No | Password for proxy authentication (if required). Example: proxy-pass. Example: |
Example Proxy Object
{ "type": "http", "host": "192.168.1.1", "port": 8080, "username": "proxy-user", "password": "proxy-pass"}socks4 auth behavior
socks4 itself does not support username / password auth like http or socks5. We still accept those fields
for consistency, but many providers ignore them. If you need authenticated SOCKS, use socks5.
Choosing a proxy
Many CAPTCHA flows verify that the same IP that solved the challenge is the IP that submits the form. If the IP changes mid-session, the token gets rejected even though the solve succeeded. Some sites are more lenient and only check that the IP came from a residential range, but the safe assumption is that the target site is doing IP matching.
The practical rule: pick a proxy that holds the same IP for the whole session, not one that gives a new IP per request.
| Type | What it is | When to use it |
|---|---|---|
| Datacenter | Cheap IPs from cloud providers. Easy to fingerprint as non-human. | Low-protection sites and smoke tests. |
| Residential | Real ISP-issued home IPs leased through proxy networks. | Most CAPTCHA-protected flows. |
| Mobile | Carrier-issued mobile IPs (4G/5G). Hardest to block. | Heavily protected flows where residential is also flagged. |
Sticky vs. rotating
- Sticky proxies keep the same IP for a session window, typically a few minutes up to an hour. Use one sticky IP for one user session (solve, submit, follow-up requests).
- Rotating proxies issue a new IP per request. This breaks IP-matching flows because every retry shows up as a different visitor.
Avoid rotating proxies
Never wire a per-request rotating proxy into the proxy field. Use sticky residential proxies and tie one IP to one
session. If your provider only sells rotating proxies, look for a "session" or "sticky" plan, or hold the same IP
yourself by reusing the same user:pass credentials.
Recommended
For most CAPTCHA-protected flows, sticky residential proxies give the best success rate without paying for mobile. Switch to mobile only when residential is consistently flagged.