reCAPTCHA v2 Solver API: g-recaptcha-response via Residential Proxy

Get a g-recaptcha-response with the SolveHub reCAPTCHA v2 API: send websiteURL, websiteKey and a residential proxy, then submit the token through the same exit with the returned user agent.

For authorized QA automation and browser integration. Use only on websites and workflows you have permission to test.

For checkbox or invisible reCAPTCHA v2, returning a g-recaptcha-response (valid for about 2 minutes). The token is bound to the websiteURL domain; use a residential proxy and submit the token through the same proxy exit with the returned userAgent. When the page carries data-s, pass recaptchaDataSValue unchanged or the token will be rejected.

Request fields

The outer type and task are required; the task.* paths below live inside the task object. Field names are case-sensitive. Length limits are in UTF-8 bytes.

Field	Type	Required	Limits	Description
`type`	string	yes	fixed `recaptcha_v2`	Platform task type.
`task`	JSON object	yes	≤ 7 MiB	Task parameters for this type.
`task.type`	string	no	must be `recaptcha_v2` when present	Legacy request format; omit in new integrations.
`task.websiteURL`	HTTP(S) URL	yes	≤ 2048 bytes	Full URL of the page hosting the reCAPTCHA.
`task.websiteKey`	non-empty string	yes	≤ 256 bytes	Page `data-sitekey` (the `k` value in the anchor).
`task.isInvisible`	boolean	no	`true` / `false`	`true` for invisible reCAPTCHA.
`task.pageAction`	non-empty string	no	≤ 512 bytes	Value of `sa` in the anchor, if present.
`task.recaptchaDataSValue`	non-empty string	no	≤ 512 bytes	Value of `s` in the anchor; required when the page carries `data-s`.
`task.apiDomain`	string	no	`www.google.com` / `www.recaptcha.net`	Domain used for reCAPTCHA requests, defaults to `www.google.com`.
`task.proxyType`	string	yes	`http` / `https` / `socks5`	Proxy scheme; a residential proxy is required.
`task.proxyAddress`	non-empty string	yes	≤ 256 bytes	Proxy address.
`task.proxyPort`	string	yes	1–5 bytes, value 1–65535	Proxy port as a quoted numeric string.
`task.proxyLogin`	non-empty string	no	≤ 256 bytes	Proxy username.
`task.proxyPassword`	non-empty string	no	≤ 256 bytes	Proxy password.

Create request example

{
  "type": "recaptcha_v2",
  "task": {
    "websiteURL": "https://example.com/login",
    "websiteKey": "6Lc_aCMTAAAAA_EXAMPLE",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080"
  }
}

cURL call

Replace the Key, site and proxy values in the example with your own; keep the same Idempotency-Key when retrying the same business request.

curl -sS -X POST 'https://www.tiam.codes/v1/tasks' \
  -H 'Authorization: Bearer sh_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-recaptcha-v2-0001' \
  --data-binary @- <<'JSON'
{
  "type": "recaptcha_v2",
  "task": {
    "websiteURL": "https://example.com/login",
    "websiteKey": "6Lc_aCMTAAAAA_EXAMPLE",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080"
  }
}
JSON

Create response and polling

A successful creation returns HTTP 202 with status usually queued. Save the taskId and poll GET /v1/tasks/{taskId} every 2–3 seconds. The soft processing window for this type is 120 seconds; beyond it a task may become uncertain, and results of accepted tasks can still be checked — do not create a replacement task with a new idempotency key.

Result fields

Read solution only when status=completed; the table lists common fields and the actual response is authoritative.

Field	Type	How to read
`solution.token`	string	The `g-recaptcha-response` token, valid for about 2 minutes.
`solution.solution`	string	Same token as `solution.token`, the generic field for token results.
`solution.userAgent`	string	Use the same User-Agent when submitting the token.

Submit the token as g-recaptcha-response to the target form and complete the request through the same proxy exit and userAgent.

Failures and troubleshooting

Use a residential proxy that passes risk checks; datacenter proxies score low or get rejected. Missing recaptchaDataSValue on a data-s page makes the token rejected.

Common creation errors are 400 INVALID_TASK, 402 INSUFFICIENT_BALANCE, 429 TASK_LIMIT_EXCEEDED and 503 TYPE_UNAVAILABLE. Failed created tasks expose TASK_FAILED or TASK_TIMEOUT; uncertain maps to TASK_UNCERTAIN. See the platform API reference.

The processing window starts when the task is created; the platform abandons unfinished tasks after about 90 seconds without charging.

reCAPTCHA v2 Solver API for Authorized Testing