createTask
Submit a CAPTCHA task with createTask: AnySolver picks a provider by your routing mode, deducts the estimate and returns a taskId to poll.
createTask validates a task, picks a provider with your routing mode, deducts the task's estimated price from your balance and returns a taskId. Poll getTaskResult with that taskId until status is ready or failed.
https://api.anysolver.com /createTaskAuthentication
Send your API key as clientKey in the JSON body, with the header Content-Type: application/json. A missing clientKey returns VALIDATION_ERROR, and an unknown key returns ERROR_KEY_DOES_NOT_EXIST.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
clientKey* | string | Yes | Your API key. Create one in a workspace of the AnySolver dashboard. |
task* | object | Yes | The task body. Required fields depend on the task type. See Tasks for per-task schemas. |
settings | object | No | Per-request settings for routing, Auto Retry, Auto Fallback, proxy reuse, response statistics and detailed analytics. Each field overrides the API key's value. See Routing modes. |
Task-specific fields go inside task; each task type's page under Tasks lists them. A task that does not match its type's schema returns VALIDATION_ERROR with a description that starts with Invalid task data: and names each failing field.
Example
{
"clientKey": "YOUR_API_KEY",
"task": {
"type": "ReCaptchaV2TokenProxyLess",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
"pageTitle": "ReCAPTCHA demo"
}
}task.proxy
Proxy task types take task.proxy as one proxy or as an array of up to 100, in string or object form, mixed freely. With Auto Retry or Auto Fallback on, each attempt takes the next proxy in the array and wraps around at the end.
{
"task": {
"proxy": [
"http://user:pass@1.2.3.4:8080",
{ "type": "http", "host": "5.6.7.8", "port": 8080, "username": "user", "password": "pass" }
]
}
}A single proxy with Auto Retry or Auto Fallback on is rejected unless you set settings.allowProxyReuse. Formats and the requirement to keep one IP for the whole solve are in Proxy configuration.
Settings
settings is optional and applies to this request only. It sets routing, Auto Retry, Auto Fallback, proxy reuse, response statistics and detailed analytics. Each field you send overrides the same field of the API key's settings, and every field you leave out keeps the key's value.
{
"clientKey": "YOUR_API_KEY",
"task": {
"type": "ReCaptchaV2TokenProxyLess",
"websiteURL": "https://example.com",
"websiteKey": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI",
"pageTitle": "Example Domain"
},
"settings": {
"routing": { "mode": "autoCheapest", "keyPoolMode": "all" },
"retry": { "enabled": true, "maxRetries": 2 },
"fallback": { "enabled": true, "maxFallbacks": 2 },
"statistics": true
}
}Auto Retry is off unless you enable it here or on the API key. Auto Fallback is on for every new API key, with maxFallbacks 2; turn it off here or in the key's settings. A task runs at most 30 attempts in total, whatever maxRetries and maxFallbacks allow. Every attempt sends the original task again, so a single-use value in it, such as a one-time token, cannot be refreshed between attempts. How attempts are chosen and charged is in Auto Retry and Auto Fallback.
settings rejects unknown fields. Invalid settings return VALIDATION_ERROR before any charge. Validation errors lists the messages.
settings.routing
| Field | Type | Required | Description |
|---|---|---|---|
mode | No | Routing mode: | |
keyPoolMode | No | Which AnySolver keys may run the task: | |
byok | No | Whether the task may run on your own provider keys: | |
provider | No | Force a specific provider for this request. Disables automatic provider selection and is incompatible with Auto Fallback. | |
providerOrder | ProviderId[] | No | Ordered provider list for |
excludedProviders | ProviderId[] | No | Providers to remove from routing entirely. They are never used for any attempt. |
settings.routing.provider sends the task to one provider and turns Auto Fallback off for the request, because there is no other provider to fall back to. Sending settings.fallback.enabled: true together with provider returns VALIDATION_ERROR.
settings.retry
Auto Retry sends the task to the same provider again after an error listed in onErrors. maxRetries accepts 0 to 10 extra attempts per provider and defaults to 2; the count starts again after each fallback.
| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | No | Enable Auto Retry. Defaults to the API key's setting, off on a new key. |
maxRetries | number | No | Maximum retries per provider (additional attempts after the first). |
onErrors | enum[] | No | Error codes that trigger a retry. Defaults to a safe set of transient errors when omitted. |
providerRules | Record<string, unknown> | No | Per-provider retry overrides. A provider only overrides the fields it defines; others inherit the defaults. |
{
"retry": {
"enabled": true,
"maxRetries": 1,
"onErrors": ["TASK_TIMEOUT", "SERVICE_UNAVAILABLE"],
"providerRules": {
"CapSolver": { "maxRetries": 3 }
}
}
}An error caused by the request itself, such as INVALID_SITEKEY, is never retried on the same provider even when onErrors lists it, because it would fail the same way. A proxy error is retried only while the array still has a proxy this task has not tried. PROVIDER_PAUSED and PROVIDER_IP_BLOCKED are never retried on the same provider. All of these can still fall back to the next provider.
settings.fallback
Auto Fallback sends the task to the next provider in the routing order after an error listed in onErrors. maxFallbacks accepts 0 to 20 extra providers and defaults to 2.
| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | No | Enable Auto Fallback. Defaults to the API key's setting, on for a new key. Cannot be true with a forced provider. |
maxFallbacks | number | No | Maximum number of additional providers to try after the first one. |
onErrors | enum[] | No | Error codes that trigger a fallback. Defaults to a safe set when omitted. |
onErrors in settings.retry and settings.fallback accepts the codes whose failure is refunded, except the six BYOK_* codes, plus PROVIDER_RESPONSE_MALFORMED and UNKNOWN_PROVIDER_ERROR. Those two continue the attempts only on providers that refund every failure. Any other code returns VALIDATION_ERROR. The BYOK_* codes always move the task on, whatever the settings (own key errors). Leave onErrors out to use the defaults listed in Auto Retry and Auto Fallback.
settings.allowProxyReuse
allowProxyReuse is a boolean and defaults to the API key's setting, which is false on a new key. It decides which proxy each attempt uses when Auto Retry or Auto Fallback is on:
false: attempts rotate through thetask.proxyarray. A task with a single proxy returnsVALIDATION_ERROR, so one IP is never sent to every attempt by accident.true: every attempt uses the first proxy intask.proxy. The other proxies in an array are never used.
Rotation across attempts shows a rotation from start to end.
settings.statistics
statistics is a boolean and defaults to the API key's Response statistics setting, which is off on a new key. With it on, getTaskResult returns a retry object with every attempt of a task that uses Auto Retry or Auto Fallback. The object is there while the task is still processing, so you can see why a slow task takes long. Turn it on for every request on the key with Response statistics on the API keys page of the key's workspace.
settings.analytics
analytics is a boolean and defaults to the API key's Detailed analytics setting, which is on for a new key. It decides whether this task counts in the per-site and per-proxy breakdowns on Provider stats. true or false overrides the key for this request only.
The breakdowns are hourly aggregates per provider, never a per-task record. They keep only this much of the request:
| Request data | Recorded as |
|---|---|
websiteURL | The hostname with its subdomains and without a leading www., such as login.example.com. |
task.proxy | The proxy type and the proxy host's registered domain, such as http and smartproxy.com. |
No path, query, fragment, port, credentials or IP address is recorded. A proxy given as an IP address shows as Direct IP, a host outside the public domain list as Private host, and an array that spans several sources as Mixed proxy sources.
- Turning
analyticsoff removes the task from these two breakdowns only. The task still counts in the provider's overall success rate and solve time, which routing uses. - Other customers see a hostname partly masked:
login.shop-example.comshows aslog**.sh***e.com. - Changing the setting does not delete statistics already recorded.
{
"clientKey": "YOUR_API_KEY",
"task": { "type": "TurnstileTokenProxyLess", "websiteURL": "https://example.com", "websiteKey": "0x4AAAAAAA" },
"settings": { "analytics": false }
}Response body
| Field | Type | Required | Description |
|---|---|---|---|
errorId* | Yes |
| |
taskId | string | No | Unique identifier returned when the task was created. |
errorCode | No | Machine-readable error code. | |
errorDescription | string | No | Human-readable error message with resolution hints. |
A successful response holds the taskId. The task's estimate has already left your balance; it is adjusted to the final price when the task ends, as Pricing and billing explains.
Examples
{
"errorId": 0,
"taskId": "01KFNDF328KAN2AJ3BNHCQYE88"
}Errors
createTask returns each of these errors before any charge, with HTTP 200.
| Error code | Cause | Fix |
|---|---|---|
ERROR_KEY_DOES_NOT_EXIST | clientKey is empty or does not match an active API key. | Copy the key again from the API keys page of its workspace, opened from Workspaces. |
ERROR_ZERO_BALANCE | Your balance is lower than the task's estimate. | Top up in Billing. |
ERROR_API_KEY_BUDGET_EXCEEDED | The estimate would take an API key spend cap past its amount. | Wait for the cap to reset, or raise it. See API key spend caps. |
ERROR_WORKSPACE_BUDGET_EXCEEDED | The estimate would take a spend cap on the key's workspace past its amount. | Wait for the cap to reset, or raise it. See Workspace spend caps. |
VALIDATION_ERROR | The body, task or settings is invalid; errorDescription names the field. | Fix the field. See Validation errors. |
RATE_LIMITED | The API key already has its maximum number of tasks in processing, or the IP sent too many requests. | Wait for tasks to finish. See Rate limits. |
NO_PROVIDERS_AVAILABLE | No provider supports the task type, none in your priority order does, or a routing rule blocks the task's parameters. | See NO_PROVIDERS_AVAILABLE. |
PROVIDER_PAUSED | Every provider that could take the task is paused. | See PROVIDER_PAUSED. |
SERVICE_UNAVAILABLE | AnySolver is at capacity and refuses new tasks. | Retry after a few seconds. |
Every code, with whether a failed task is refunded: Error handling.
Validation errors
Invalid settings return VALIDATION_ERROR with one of these messages in errorDescription. When a request has several problems, the messages are joined with ; .
| Message | Fix |
|---|---|
settings.routing.providerOrder can only be used when settings.routing.mode is "priority". | Remove providerOrder, or set mode to priority. |
settings.routing.provider: settings.routing.provider cannot be used with settings.routing.mode "autoCheapest". … | Remove the auto* mode, or remove provider. |
settings.fallback.enabled: settings.fallback.enabled cannot be true when settings.routing.provider is used, … | Remove fallback.enabled, or remove provider. |
Priority routing requires a provider order. … | Add providerOrder, or save a priority order on the API key. |
settings.routing.providerOrder: Provider "CapSolver" cannot be in both … | Remove the provider from providerOrder or from excludedProviders. |
settings.routing.provider: Provider "CapSolver" cannot be used because it is also listed in … | Remove provider, or remove that provider from excludedProviders. |
settings.routing.excludedProviders excludes every provider that supports this task type. | Exclude fewer providers. |
A single proxy with auto retry or fallback enabled would reuse the same IP on every attempt. … | Send several proxies in task.proxy, or set allowProxyReuse to true. |
settings.retry.onErrors.0: Unsupported error code: … | Use only codes onErrors accepts, listed in settings.fallback. |
Unknown field settings.allowProxyReUse. Did you mean settings.allowProxyReuse? | Correct the field name. |
Do not combine legacy top-level routing fields (provider, selectionMode, keyPoolMode) with settings; … | Move the routing fields into settings.routing. |
settings.routing.keyPoolMode: settings.routing.keyPoolMode has no effect when settings.routing.byok is "only": … | Remove keyPoolMode or byok. A task on own keys only never runs on AnySolver keys. |
Related
Overview
The base URL, API key authentication, JSON response envelope, errorId values and rate limits that every AnySolver API endpoint shares, with examples.
POSTgetTaskResult
Poll getTaskResult with a taskId to read the task status and, once it is ready, its solution and final cost. Polling is free, only the task is charged.