reCAPTCHA v2

A reCAPTCHA v2 task returns a token (gRecaptchaResponse) that you submit to the target site to pass the check, without clicking any images. The most common type, NoCaptchaTaskProxyless, costs 15 points (¥0.015) per task and is asynchronous: create the task with createTask, then call getTaskResult every 5 seconds for the result. Failed and timed-out tasks are refunded automatically.

POSThttps://api.yescaptcha.com/createTaskGlobal endpointCopy

POSThttps://cn.yescaptcha.com/createTaskChina endpointCopy

The request body is JSON and is authenticated with your clientKey (copy it from the yescaptcha.com dashboard). Query results on the same endpoint you created the task on.

When to use

• The page shows an “I’m not a robot” checkbox: the checkbox version.
• There is no checkbox, and an image challenge appears only after you click a submit button: the invisible version. Add "isInvisible": true.
• The page loads recaptcha/enterprise.js, or the request URLs contain enterprise: reCAPTCHA Enterprise. Use a type with Enterprise in its name.

If you are not sure which one you have, see Identify the captcha type. If tokens do not pass often enough, try reCAPTCHA v2 image recognition: the API tells you which tiles to click, and you click them in the browser.

Task types and pricing

Task type	Price	Mode	Notes
NoCaptchaTaskProxyless	15 points (¥0.015)	Asynchronous
RecaptchaV2TaskProxyless	20 points (¥0.02)	Asynchronous	Same parameters as NoCaptchaTaskProxyless on a different route; use either as a fallback
NoCaptchaTask	15 points (¥0.015)	Asynchronous	Own proxy
RecaptchaV2EnterpriseTaskProxyless	20 points (¥0.02)	Asynchronous
RecaptchaV2EnterpriseTask	20 points (¥0.02)	Asynchronous	Own proxy

• NoCaptchaTaskProxyless and RecaptchaV2TaskProxyless take the same parameters on different routes. If one does not pass often enough, try the other.
• Types without Proxyless in the name (NoCaptchaTask, RecaptchaV2EnterpriseTask) load the captcha through your own proxy and need proxyType, proxyAddress, proxyPort and related fields. Use them when the target site checks the visitor’s IP.

Request parameters

Fields of the task object in createTask:

Field	Type	Required	Description
type	string	Yes	Task type; see "Task types and pricing" on this page
websiteURL	string	Yes	Full URL of the page that shows the captcha. Use the site you see the captcha on, not the captcha vendor's domain
websiteKey	string	Yes	The site key (sitekey), found in the page source or network requests; usually does not change
isInvisible	boolean	No	Set to true for the invisible variant; omit otherwise
proxyType	string	Required for NoCaptchaTask, RecaptchaV2EnterpriseTask	Proxy protocol: http, https, socks4 or socks5
proxyAddress	string	Required for NoCaptchaTask, RecaptchaV2EnterpriseTask	Proxy IP address or hostname. Local or private addresses such as 127.0.0.1 or 192.168.x.x will not work because our servers cannot reach them
proxyPort	integer	Required for NoCaptchaTask, RecaptchaV2EnterpriseTask	Proxy port
proxyLogin	string	No	Proxy username, if the proxy requires authentication (NoCaptchaTask, RecaptchaV2EnterpriseTask only)
proxyPassword	string	No	Proxy password, if the proxy requires authentication (NoCaptchaTask, RecaptchaV2EnterpriseTask only)
userAgent	string	No	Browser User-Agent. If the result contains a userAgent, use that value when you submit the token (NoCaptchaTask, RecaptchaV2EnterpriseTask only)
enterprisePayload	object	No	Extra enterprise parameters, such as the reCAPTCHA Enterprise s value: {"s": "..."}. Omit if the page does not use it (RecaptchaV2EnterpriseTaskProxyless, RecaptchaV2EnterpriseTask only)

To find websiteURL and websiteKey, see Find reCAPTCHA parameters.

Request example

Using Google’s official demo page:

POST https://api.yescaptcha.com/createTask

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "NoCaptchaTaskProxyless",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
  }
}

Complete code that creates the task, polls every 5 seconds and prints the token. Put your client key in the environment variable YESCAPTCHA_CLIENT_KEY before running it:

curl

curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "NoCaptchaTaskProxyless",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
  }
}'

# Returns {"errorId":0,"taskId":"..."}; then poll every 5 seconds:
curl -s https://api.yescaptcha.com/getTaskResult \
  -H 'Content-Type: application/json' \
  -d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'

Python

solve.py

import os
import time

import requests

API = "https://api.yescaptcha.com"
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]  # Read the clientKey from an environment variable


def call(method, payload):
    r = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30)
    data = r.json()
    if data.get("errorId"):
        raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
    return data


def solve(task):
    task_id = call("createTask", {"task": task})["taskId"]
    for _ in range(36):  # Poll every 5 seconds, for up to about 3 minutes
        time.sleep(5)
        result = call("getTaskResult", {"taskId": task_id})
        if result.get("status") == "ready":
            return result["solution"]
    raise TimeoutError(task_id)


solution = solve({
    "type": "NoCaptchaTaskProxyless",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})
print(solution["gRecaptchaResponse"])

Node.js

solve.mjs

const API = 'https://api.yescaptcha.com';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY; // Read the clientKey from an environment variable

async function call(method, payload) {
  const res = await fetch(`${API}/${method}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ clientKey: CLIENT_KEY, ...payload }),
  });
  const data = await res.json();
  if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
  return data;
}

async function solve(task) {
  const { taskId } = await call('createTask', { task });
  for (let i = 0; i < 36; i++) { // Poll every 5 seconds, for up to about 3 minutes
    await new Promise((r) => setTimeout(r, 5000));
    const result = await call('getTaskResult', { taskId });
    if (result.status === 'ready') return result.solution;
  }
  throw new Error(`timeout: ${taskId}`);
}

const solution = await solve({
  type: "NoCaptchaTaskProxyless",
  websiteURL: "https://www.google.com/recaptcha/api2/demo",
  websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
console.log(solution.gRecaptchaResponse);

For reCAPTCHA Enterprise, if the page passes an s value to reCAPTCHA, put it in enterprisePayload:

POST https://api.yescaptcha.com/createTask

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "RecaptchaV2EnterpriseTaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "SITE_KEY_OF_THE_PAGE",
    "enterprisePayload": {
      "s": "S_VALUE_FROM_THE_PAGE"
    }
  }
}

With your own proxy:

POST https://api.yescaptcha.com/createTask

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "NoCaptchaTask",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    "proxyType": "http",
    "proxyAddress": "proxy.example.com",
    "proxyPort": 8080,
    "proxyLogin": "user",
    "proxyPassword": "pass"
  }
}

Result

createTask returns a task ID:

{ "errorId": 0, "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006" }

Call getTaskResult with it. While the task is in progress you get {"errorId": 0, "status": "processing"}; check again 5 seconds later. When it is done:

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
  }
}

Field	Type	Description
gRecaptchaResponse	string	The token to submit to the target site. Single use, valid for about 120 seconds; use it within 60 seconds

A task runs for at most about 110 seconds; after that it returns ERROR_TASK_TIMEOUT and the points are refunded. On errors errorId is 1; handle them by errorCode as described in Error codes. For how to submit the token, see Submit a reCAPTCHA token.

FAQ

Why do tokens for the same site sometimes pass and sometimes fail?

The target site decides. It scores each verification against a threshold that it can change at any time, so pass rates differ between sites and not every token passes. Compare another task type for the same captcha, or switch to image recognition.

How long is a token valid?

Tokens are single use and valid for about 120 seconds. Submit within 60 seconds. Google sets this limit.

Am I charged when solving fails?

No. Tasks that return ERROR_CAPTCHA_UNSOLVABLE or time out are refunded automatically. See Billing and refunds.

Related guides

• Identify the captcha type
• Find reCAPTCHA parameters
• Submit a reCAPTCHA token
• reCAPTCHA image clicking with Selenium