Skip to Content
AnySolver logo
AnySolver
Async

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.

POSThttps://api.anysolver.com/createTask

Authentication

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

FieldTypeRequiredDescription
clientKey*
stringYes

Your API key. Create one in a workspace of the AnySolver dashboard.

task*
objectYes

The task body. Required fields depend on the task type. See Tasks for per-task schemas.

settings
objectNo

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.

Array of proxies, one per attempt
{
    "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.

POST /createTask with settings
{
    "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

FieldTypeRequiredDescription
mode
No

Routing mode: priority, autoCheapest, autoFastest, or autoMostReliable. Overrides the API key default. See Routing modes.

keyPoolMode
No

Which AnySolver keys may run the task: all (default, AnySolver's keys and keys contributed through Provider Exchange) or platformOnly (AnySolver's keys only). Never affects your own keys. See Key pool mode.

byok
No

Whether the task may run on your own provider keys: first (default, your own keys first, then AnySolver keys at the normal price when none of yours can run it), only (your own keys only; the task fails with a BYOK_* error and costs nothing when none can run it) or off (AnySolver keys only). Overrides the API key's and the workspace's default. See Bring your own 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 priority routing. The first provider that supports the task is used; the rest form the fallback order. Only valid when mode is priority.

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.

FieldTypeRequiredDescription
enabled
booleanNo

Enable Auto Retry. Defaults to the API key's setting, off on a new key.

maxRetries
numberNo

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 with a rule for one provider
{
    "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.

FieldTypeRequiredDescription
enabled
booleanNo

Enable Auto Fallback. Defaults to the API key's setting, on for a new key. Cannot be true with a forced provider.

maxFallbacks
numberNo

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 the task.proxy array. A task with a single proxy returns VALIDATION_ERROR, so one IP is never sent to every attempt by accident.
  • true: every attempt uses the first proxy in task.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 dataRecorded as
websiteURLThe hostname with its subdomains and without a leading www., such as login.example.com.
task.proxyThe 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 analytics off 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.com shows as log**.sh***e.com.
  • Changing the setting does not delete statistics already recorded.
Leave one request out of detailed analytics
{
    "clientKey": "YOUR_API_KEY",
    "task": { "type": "TurnstileTokenProxyLess", "websiteURL": "https://example.com", "websiteKey": "0x4AAAAAAA" },
    "settings": { "analytics": false }
}

Response body

FieldTypeRequiredDescription
errorId*
Yes

0 on success; 1 or 2 on an error. Branch on errorCode: Error IDs explains the two error groups.

taskId
stringNo

Unique identifier returned when the task was created.

errorCode
No

Machine-readable error code.

errorDescription
stringNo

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 codeCauseFix
ERROR_KEY_DOES_NOT_EXISTclientKey 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_BALANCEYour balance is lower than the task's estimate.Top up in Billing.
ERROR_API_KEY_BUDGET_EXCEEDEDThe 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_EXCEEDEDThe 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_ERRORThe body, task or settings is invalid; errorDescription names the field.Fix the field. See Validation errors.
RATE_LIMITEDThe 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_AVAILABLENo 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_PAUSEDEvery provider that could take the task is paused.See PROVIDER_PAUSED.
SERVICE_UNAVAILABLEAnySolver 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 ; .

MessageFix
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.