getTaskResult

After creating a task with createTask, use this endpoint to poll for the result. Continue polling until the status is ready (solution available) or failed (task could not be solved).

Endpoint

POST https://api.ucaptcha.net/getTaskResult

Request

{
  "clientKey": "YOUR_API_KEY",
  "taskId": "550e8400-e29b-41d4-a716-446655440000"
}

Request Parameters

Parameter	Type	Required	Description
clientKey	string	Yes	Your API key
taskId	string	Yes	Task ID returned by createTask

Response

Processing

The task is still being solved. Continue polling.

{
  "errorId": 0,
  "status": "processing"
}

Ready

The task completed successfully. The solution object contains the result.

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "03AGdBq24PBCbwiDRkh3FOcMZ1Xi5sEKH..."
  },
  "cost": 0.00299,
  "solveTime": 12400
}

Failed

The provider could not solve the captcha. The charge is automatically refunded.

{
  "errorId": 0,
  "status": "failed",
  "errorCode": "ERROR_CAPTCHA_UNSOLVABLE",
  "errorDescription": "Provider could not solve the captcha"
}

Response Parameters

Field	Type	Description
errorId	number	0 for a valid response, 1 for a request-level error
status	string	idle, processing, ready, or failed
solution	object	Solution object containing the result (only when status is ready)
cost	number	Actual cost in USD (only when status is ready)
solveTime	number	Time to solve in milliseconds (only when status is ready)
errorCode	string	Error code (only when status is failed)
errorDescription	string	Human-readable error message (only when status is failed)

The contents of the solution object depend on the task type. For example, reCAPTCHA tasks return gRecaptchaResponse, hCaptcha tasks return token, and image recognition tasks return text. See the individual task type pages for details.

Polling Best Practices

• Poll every 5 seconds. Polling more frequently does not speed up solving and counts against your rate limit.
• Set a maximum timeout of approximately 5 minutes (60 poll attempts). If a task has not completed by then, it is unlikely to succeed.
• Check the status field first. Only access solution when status is ready.

Note

Failed tasks are automatically refunded. You do not need to take any action to reclaim the balance.

Tip

To avoid polling entirely, use callbacks to receive results via webhook.

Code Examples

cURL

curl -X POST https://api.ucaptcha.net/getTaskResult \
  -H "Content-Type: application/json" \
  -d '{
    "clientKey": "YOUR_API_KEY",
    "taskId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Python

import requests
import time

task_id = "550e8400-e29b-41d4-a716-446655440000"

for attempt in range(60):
    response = requests.post("https://api.ucaptcha.net/getTaskResult", json={
        "clientKey": "YOUR_API_KEY",
        "taskId": task_id
    })

    data = response.json()

    if data["errorId"] != 0:
        print(f"Error: {data['errorCode']}")
        break

    if data["status"] == "ready":
        print(f"Solution: {data['solution']}")
        print(f"Cost: ${data['cost']}")
        print(f"Solve time: {data['solveTime']}ms")
        break

    if data["status"] == "failed":
        print(f"Task failed: {data['errorCode']}")
        break

    # Still processing, wait and retry
    time.sleep(5)
else:
    print("Timed out waiting for solution")

JavaScript

async function getTaskResult(clientKey, taskId) {
  for (let attempt = 0; attempt < 60; attempt++) {
    const response = await fetch("https://api.ucaptcha.net/getTaskResult", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ clientKey, taskId }),
    });

    const data = await response.json();

    if (data.errorId !== 0) {
      throw new Error(`${data.errorCode}: ${data.errorDescription}`);
    }

    if (data.status === "ready") {
      return data.solution;
    }

    if (data.status === "failed") {
      throw new Error(`Task failed: ${data.errorCode}`);
    }

    // Still processing, wait 5 seconds
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }

  throw new Error("Timed out waiting for solution");
}

// Usage
const solution = await getTaskResult("YOUR_API_KEY", "550e8400-e29b-41d4-a716-446655440000");
console.log("Solution:", solution);