reCAPTCHA v3

reCAPTCHA v3 has no checkbox and no images; the page scores visitors in the background. YesCaptcha returns a token (gRecaptchaResponse) that you submit to the target site. RecaptchaV3TaskProxyless costs 20 points (¥0.02) per task and is asynchronous: createTask, then getTaskResult every 5 seconds. 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 authenticated with your clientKey. Query results on the same endpoint you created the task on.

When to use

• The page source contains grecaptcha.execute(...), or it loads recaptcha/api.js?render=SITE_KEY: reCAPTCHA v3.
• It calls grecaptcha.enterprise.execute(...) or loads recaptcha/enterprise.js: reCAPTCHA v3 Enterprise. Use RecaptchaV3EnterpriseTask or RecaptchaV3EnterpriseTaskM1.

How to tell: Identify the captcha type.

Task types and pricing

Task type	Price	Mode	Notes
RecaptchaV3TaskProxyless	20 points (¥0.02)	Asynchronous
RecaptchaV3TaskProxylessM1	25 points (¥0.025)	Asynchronous
RecaptchaV3TaskProxylessM1S7	30 points (¥0.03)	Asynchronous	Requests a score of 0.7; no extra parameter needed
RecaptchaV3TaskProxylessM1S9	35 points (¥0.035)	Asynchronous	Requests a score of 0.9; no extra parameter needed
RecaptchaV3EnterpriseTask	20 points (¥0.02)	Asynchronous
RecaptchaV3EnterpriseTaskM1	25 points (¥0.025)	Asynchronous

• RecaptchaV3TaskProxyless and RecaptchaV3TaskProxylessM1 take the same parameters on different routes; use either as a fallback for the other.
• If the target site requires a high score, use RecaptchaV3TaskProxylessM1S7 (0.7) or RecaptchaV3TaskProxylessM1S9 (0.9); no extra parameter is needed.

Request parameters

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
pageAction	string	No	The reCAPTCHA v3 action; it must match the value the page passes to grecaptcha.execute, or the token may be rejected

pageAction must match the action the page passes to grecaptcha.execute(SITE_KEY, {action: '...'}), or the site may reject the token. How to find it: Find reCAPTCHA parameters.

Request example

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

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "RecaptchaV3TaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "SITE_KEY_OF_THE_PAGE",
    "pageAction": "login"
  }
}

curl

curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "RecaptchaV3TaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "SITE_KEY_OF_THE_PAGE",
    "pageAction": "login"
  }
}'

# 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": "RecaptchaV3TaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "SITE_KEY_OF_THE_PAGE",
    "pageAction": "login",
})
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: "RecaptchaV3TaskProxyless",
  websiteURL: "https://example.com/login",
  websiteKey: "SITE_KEY_OF_THE_PAGE",
  pageAction: "login",
});
console.log(solution.gRecaptchaResponse);

Replace websiteURL, websiteKey and pageAction with the target site’s values.

Result

{
  "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

While in progress you get {"errorId": 0, "status": "processing"}; check again 5 seconds later. Handle errors by errorCode as described in Error codes. To submit the token, see Submit a reCAPTCHA token.

FAQ

Why are some tokens rejected by the site?

With v3 the target site decides based on the score, and it can change its threshold at any time, so not every token passes. Make sure pageAction is correct, try M1S7 or M1S9 if the site needs a high score, or compare other types.

How do I fill in v3 Enterprise?

The same as v3: websiteURL, websiteKey, pageAction, with the type RecaptchaV3EnterpriseTask or RecaptchaV3EnterpriseTaskM1.

How long is a token valid?

Single use, valid for about 120 seconds. Submit within 60 seconds.

Related guides

• Identify the captcha type
• Find reCAPTCHA parameters (including pageAction)
• Submit a reCAPTCHA token