createTask
Create a new CAPTCHA solving task.
Endpoint
POST /createTaskDescription
Creates a new task to solve a CAPTCHA. The task is queued and processed by the selected provider based on your routing strategy.
Request
Headers
| Header | Value |
|---|---|
| Content-Type | application/json |
Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
clientKey | string | Yes | Your API key from the dashboard |
task | object | Yes | Task configuration object |
task.type | string | Yes | The task type (e.g., ReCaptchaV2Token) |
selectionMode | string | No | Override routing mode: autoCheapest, autoFastest, autoMostReliable, priority |
keyPoolMode | string | No | Key pool to use: all (default) or platformOnly. See below. |
provider | string | No | Force a specific provider (bypasses routing) |
Additional parameters depend on the task type. See Tasks for full schemas.
Key Pool Mode
Controls which provider keys are used to solve your task:
all(default): Uses all available keys, including community-contributed keys from the Provider Exchange. Larger pool, fewer rate limits, faster solves.platformOnly: Restricts to platform-managed keys only. Useful if you value privacy and don't want tasks routed through community-contributed keys.
You can set a default per API key in API Keys → Edit → Platform Keys Only. A per-request value overrides the key default.
Example Request
{ "clientKey": "your-api-key-from-dashboard", "task": { "websiteURL": "https://www.google.com/recaptcha/api2/demo", "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-", "pageTitle": "reCAPTCHA demo", "type": "ReCaptchaV2TokenProxyLess" }}Response
Success Response
{
"errorId": 0,
"taskId": "7c1e1d3a-7e8f-4d4f-8e5d-5c9e7d8a9b1c"
}| Field | Type | Description |
|---|---|---|
errorId | number | 0 indicates no error |
taskId | string | Unique identifier for the created task |
Error Response
{
"errorId": 1,
"errorCode": "INVALID_TASK_DATA",
"errorDescription": "Invalid or missing task parameters. Check request structure."
}| Field | Type | Description |
|---|---|---|
errorId | number | 1 = external error, 2 = internal error |
errorCode | string | Machine-readable error code |
errorDescription | string | Human-readable error message |
Common Errors
| Error Code | Description |
|---|---|
ERROR_KEY_DOES_NOT_EXIST | Invalid or missing API key |
ERROR_ZERO_BALANCE | Insufficient account balance |
INVALID_TASK_DATA | Missing or invalid task parameters |
TASK_NOT_SUPPORTED | Task type not supported |
NO_PROVIDERS_AVAILABLE | No providers available for this task type |
See Error Handling for the complete list.
Flow
- Authentication: Validates your
clientKey - Rate Limiting: Checks request rate limits
- Routing: Selects provider based on your routing strategy
- Balance Deduction: Estimates cost and deducts from your balance (refunded if task fails)
- Task Creation: Sends task to provider and enqueues polling job
- Response: Returns
taskIdfor result polling
See Pricing & Billing for how costs are calculated and reconciled.
Next Steps
After creating a task, poll for results using getTaskResult.
Polling Interval
Wait 3-5 seconds before the first poll, then poll every 2-3 seconds. Most tasks complete within 10-30 seconds.