reCAPTCHA v3 Solver API: Token and Score via REST

Request a reCAPTCHA v3 token and 0.0–1.0 score for a given action through the SolveHub API; scores depend on proxy reputation and are never guaranteed.

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

For reCAPTCHA v3, returning a g-recaptcha-response token and a 0.0–1.0 score. The score is assessed by Google from the IP and browser environment and is not guaranteed to reach minScore; use a clean residential proxy.

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_v3`	Platform task type.
`task`	JSON object	yes	≤ 7 MiB	Task parameters for this type.
`task.type`	string	no	must be `recaptcha_v3` when present	Legacy request format; omit in new integrations.
`task.websiteURL`	HTTP(S) URL	yes	≤ 2048 bytes	Full URL of the page running reCAPTCHA v3.
`task.websiteKey`	non-empty string	yes	≤ 256 bytes	The reCAPTCHA v3 site key.
`task.action`	non-empty string	no	≤ 256 bytes	Action expected by the site (for example `login`), defaults to `verify`.
`task.minScore`	number	no	0.0–1.0	Desired minimum score, a hint only.
`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_v3",
  "task": {
    "websiteURL": "https://example.com/",
    "websiteKey": "6Lc_aCMTAAAAA_EXAMPLE",
    "action": "verify",
    "minScore": 0.7,
    "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-v3-0001' \
  --data-binary @- <<'JSON'
{
  "type": "recaptcha_v3",
  "task": {
    "websiteURL": "https://example.com/",
    "websiteKey": "6Lc_aCMTAAAAA_EXAMPLE",
    "action": "verify",
    "minScore": 0.7,
    "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.
`solution.solution`	string	Same token as `solution.token`, the generic field for token results.
`solution.score`	number, optional	The 0.0–1.0 score returned by Google.
`solution.userAgent`	string	Use the same User-Agent when submitting the token.

Submit the token as g-recaptcha-response through the same proxy exit and userAgent; when the score is too low, switch to a cleaner proxy or lower minScore and retry.

Failures and troubleshooting

minScore is a hint only and does not guarantee the resulting score; the page action must match what the site actually calls, or risk checks reject the token.

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.