Bring your own keys (BYOK)
Run AnySolver tasks on your own CapSolver, 2Captcha or other provider keys with the same API, routing and fallback, and a fee only past a free allowance.
Add your own provider keys and AnySolver runs your tasks on them: the provider bills your account, and AnySolver charges a fee only after a free monthly allowance. You keep one API, one request format and the same routing, Auto Retry and Auto Fallback. You decide per workspace, per API key or per request what happens when none of your keys can run a task.
settings.routing.byok | What runs the task | Use it when |
|---|---|---|
first (default) | Your own keys run each task first. If none can, it continues on AnySolver keys at the normal price. | A task should always complete, on your key whenever possible |
only | Only your own keys run tasks. If none can, the task fails with a BYOK_* error at no charge. | Every task must run on your own provider account, or not at all |
off | Tasks run on AnySolver keys at the normal price. | A workspace or API key should not touch your provider accounts |
Add a key
- Open BYOK and click Add key.
- Pick the Provider, give the key a Label (shown in task details and alerts), and paste the Provider API key.
- Under Workspaces, choose All workspaces (every workspace, including new ones) or Selected workspaces and tick them. All workspaces needs access to every workspace.
- For your organization's first key, answer When none of your own keys can run a task. The question shows only to a member who also holds Workspaces: Edit. See the first key's question for what each answer saves.
- Optionally, open Connection proxy, threads and spend caps to set a connection proxy, Max threads or spend caps.
- Click Add key.
A new key is saved as Checking, and AnySolver checks it within seconds by asking the provider for its balance, through the connection proxy when the key has one. The key then shows Active with that balance, or a problem status with the provider's reason. AnySolver stores the key encrypted and shows only its last four characters from then on. A key belongs to one organization at a time, and a key you contribute to Provider Exchange cannot be added as your own key, or the other way round.
The first key's question
The answer to When none of your own keys can run a task is saved as the default of the workspaces the key covers, in the same step as the key:
| Answer | What it saves |
|---|---|
| Continue on AnySolver keys | Nothing: first is every workspace's default already. |
| Stop the task | The covered workspaces still on the default first move to only. Workspaces set to off stay. |
The dialog preselects Stop the task when your balance is empty, since first needs balance (see what it costs). Later keys do not ask: change a workspace's choice in its Settings (see choose first, only or off).
Who can manage keys
Adding, editing, replacing and removing keys needs the Own provider keys: Edit permission, and seeing them needs Own provider keys: Read (see permissions). Changing a key's spend caps also needs Spend limits: Edit. A member who reaches only some workspaces sees the keys of those workspaces plus organization-wide keys, and changes only keys whose workspaces they all reach.
The Fees this month card on the BYOK page needs Billing: Read. A member without Own provider keys: Read sees that a task ran on an own key in its task details, but not the key's label.
Archived workspaces
Archiving a workspace removes it from every own key's workspaces. A key that covered only archived workspaces is turned off and shows Off, and the audit log records it. Pick new workspaces for it under Edit, then Turn on in the key's menu.
How tasks pick a key
AnySolver ranks providers for the task exactly as without your keys: routing mode, providerOrder, excludedProviders and a forced provider all apply first. Then:
- The providers you have a usable key for move to the front, in ranked order, each running on your key.
- With
first, every ranked provider follows on AnySolver keys. Withonly, nothing follows. - For one provider with several of your keys, keys limited to the task's workspace go before organization-wide keys, in random order within each group so load spreads.
Own keys outrank the routing mode: with autoFastest, a provider you have a key for runs before a faster one you do not. autoCheapest ranks by AnySolver's listed prices, not by your own rates at the provider.
With first, a provider you have a key for appears twice in the list: on your keys, then on AnySolver's.
When the provider refuses your key (invalid, out of balance, IP not allowed) or its connection proxy fails, AnySolver marks the key and tries your next key for the same provider. When none is left, the attempt ends with that problem's BYOK_* code and the task moves on to the next entry in the list, whatever your Auto Fallback settings say. The same holds when your keys for the provider are all at a cap or all full.
A provider that is paused, or that a routing rule keeps away from the task, is passed over as on AnySolver keys. Passing from your keys to AnySolver's keys on that same provider is a free move.
Free moves, and the moves past your keys above, count toward the 30-attempt limit but not toward maxFallbacks. They still show as kind: "fallback" in the attempts and in the fallbacks count of retry.
A solving failure on your key, such as CAPTCHA_UNSOLVABLE, follows your Auto Retry and Auto Fallback settings exactly as on AnySolver keys. Only CAPTCHA_UNSOLVABLE makes a fallback skip the providers it happened on. An unsolvable on your CapSolver key therefore does not go to CapSolver again on AnySolver keys. Any other failure on your key still lets the task fall back to AnySolver's key for the same provider: a rate limit on your provider account, a timeout or an outage, for example.
Choose first, only or off
The setting resolves in this order, the first one set wins:
settings.routing.byokin thecreateTaskrequest.- Own keys on the API key, under Advanced settings (Workspace default follows the workspace).
- Own keys in the workspace's Settings.
first.
The dashboard names the values Own keys first (first), Own keys only (only) and AnySolver keys only (off). Choosing Own keys only on an API key or a workspace needs Own provider keys: Edit on top of API keys: Edit or Workspaces: Edit.
An organization without keys sees no change from first. To run one request on your keys only:
{
"clientKey": "YOUR_API_KEY",
"task": {
"type": "ReCaptchaV2TokenProxyLess",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
"pageTitle": "ReCAPTCHA demo"
},
"settings": { "routing": { "byok": "only" }, "statistics": true }
}keyPoolMode chooses among AnySolver keys only (all, or platform only) and never affects your keys. Sending keyPoolMode together with "byok": "only" in the same request returns VALIDATION_ERROR, since that task never runs on AnySolver keys (see validation errors).
What it costs
| Outcome | AnySolver charges |
|---|---|
| Solved on your key, within the month's free allowance | Nothing |
| Solved on your key, past the free allowance | 2% of AnySolver's listed price for the task on that provider, rounded up to $0.000001 |
| Failed on your key, for any reason | Nothing, also when the provider does not refund the failure |
| Moved from your key to AnySolver keys | The normal price, refunded on failure as usual |
The free allowance runs per organization and calendar month (UTC) and has two limits; whichever your solved tasks on your keys reach first ends it:
- $500 of tasks, each counted at its listed price, so the allowance is worth the same whatever your tasks cost. The task that crosses $500 pays the fee only on its part above it.
- 5,000,000 tasks, which only comes first for tasks averaging under $0.10 per 1,000.
For example, CapSolver lists ReCaptchaV2TokenProxyLess at $0.0008: the first 625,000 such solves in a month are free, each one after that costs $0.000016, and 1,000,000 solves in a month cost $6.00 at AnySolver. A task listed at $0.10 per 1,000 reaches both limits together at 5,000,000 solves, and 30,000,000 of them in a month cost $50.00. The provider bills your account for the solve itself, at your rate there. The BYOK page shows the month's solved tasks, the free allowance left and fees, and alerts arrive at 80% and 100% of the allowance.
The fee is paid from your AnySolver balance, so the deposit fee applies to the fee alone, not to what the provider bills you. At the default 5% deposit fee, that is 2.1% of the listed price in all.
The estimate taken at createTask covers the most the task can cost:
- With
first, the estimate is the normal price of the first attempt on AnySolver keys, so the task needs that much balance. When it ends on your key, everything but the fee comes back at settlement. - With
only, the estimate is the fee, or $0 within the free allowance, so a task runs with an empty balance until the allowance is used.
A first task whose estimate the balance cannot cover returns ERROR_ZERO_BALANCE before any charge, with a description pointing at "byok": "only". The same holds for an API key spend cap or a workspace spend cap.
Connection proxy
The connection proxy is the HTTP or HTTPS proxy AnySolver connects through when it calls the provider with your key, set per key. Use it when your provider account only accepts the key from allowed IPs, or when the provider should see your IP. It is not the task proxy you send in task.proxy, which the provider solves the CAPTCHA through.
Set it in Add key or Edit under Connection proxy, threads and spend caps, as http://user:password@proxy.example.com:8080. The rules:
http://andhttps://proxies only, on a public internet address. AnySolver refuses private addresses (such as10.0.0.0/8and192.168.0.0/16), loopback, link-local and carrier-grade NAT (100.64.0.0/10) addresses. It also refuses reserved addresses (including the documentation ranges such as203.0.113.0/24) and AnySolver's own hosts, when you save and again on every connection.- Provider APIs are HTTPS, so the proxy carries an encrypted tunnel and never sees your key.
- AnySolver stores the URL encrypted and shows only its host and port.
- A new proxy is checked at once: the key shows Checking again after you save it.
The proxy is blamed only when a request failed before its tunnel to the provider was up. That is a proxy that cannot be reached or whose name does not resolve, no connection within 10 seconds, or a 4xx answer to the tunnel request, such as for wrong credentials. Each of these marks the key Proxy unreachable and ends the attempt with BYOK_PROXY_FAILED. A timeout, a reset or a TLS error after the tunnel is up, and a 5xx answer from the proxy, count as provider failures and leave the key as it is. While AnySolver polls a task, a proxy that stays down through the poll's retries ends the attempt with BYOK_PROXY_FAILED and marks the key.
When a provider blocks an IP
A provider that answers your key with an IP block blames the IP the request came from, and AnySolver treats it as your key's problem:
| Your key | Key status | Attempt ends with | What to do |
|---|---|---|---|
| Has a connection proxy | Proxy unreachable | BYOK_PROXY_FAILED | Use a proxy on another IP. |
| Has no connection proxy | Rejected | BYOK_KEY_INVALID | Set a connection proxy on an IP the provider allows. |
It never pauses the provider for anyone else. The other way round, while a provider blocks AnySolver's own IP and is paused for every account, your keys behind their own connection proxy keep running on it. Own keys for that provider without a proxy wait out the pause like AnySolver's keys, and the task moves on.
Thread limit
A provider plan sold in threads limits how many tasks a key may run at once. Set Max threads in Add key or Edit under Connection proxy, threads and spend caps, for example 200 for a 200-thread plan, from 1 to 100,000. Leave it empty for no limit.
AnySolver counts the tasks each key is running and never starts one more than the limit, even under bursts. A full key is skipped, not marked: it stays Active. If an AnySolver worker stops while it hands a task to the provider, that task's thread frees itself within 6 minutes. When every own key for this provider is full:
- With
first, the task continues on AnySolver keys at the normal price, and its attempts show the full key asBYOK_THREAD_LIMIT_REACHED. - With
only, the task fails withBYOK_THREAD_LIMIT_REACHEDat no charge.
The Threads column on the BYOK page shows how many tasks each key is running now, against its limit.
Spend caps
A key can carry spend caps per period of hours, days or weeks, or in total, set in Add key or Edit under Spend caps on this key. Changing them needs Spend limits: Edit on top of Own provider keys: Edit. They count each task at AnySolver's listed price for it on that provider, which is what the provider charges unless you have a discount there: your provider bill stays the source of truth. Periods are fixed UTC windows, counted the same way as API key spend caps.
An attempt that takes the key reserves that price against every cap on it before it starts, the same way API key and workspace spend caps reserve. Concurrent tasks therefore cannot pass a cap. A failed attempt that the provider does not charge for hands its reservation back. A solved task keeps it, and so does a failure the provider keeps the charge for.
- A period cap the attempt would pass skips the key for this attempt only, and the next key for the provider is tried.
- A total cap the attempt would pass stops the key: it shows At its cap, and the organization gets an alert.
- Lowering a total cap to what the key already spent, or below, stops the key at once.
- A key at its total cap runs again when you raise the cap above its spend or remove it. Turning the key off and on also frees it, and restarts its total from zero. Replacing the key keeps it at its cap.
When every own key for the provider is at a cap, the attempt ends with BYOK_KEY_LIMIT_REACHED.
API key and workspace spend caps count what AnySolver charges, fees included. What a task costs on your key counts only against that key's own caps.
Key statuses
| Status | What it means | What happens next |
|---|---|---|
| Checking | AnySolver is asking the provider about the key. | Checked within seconds. A provider without a balance call is checked by the key's first task. |
| Active | The key runs tasks. The provider balance is rechecked every 10 minutes. | Nothing to do. |
| Rejected | The provider refused the key: invalid, revoked, or not allowed from the IP. | Rechecked from every minute to every hour. Use Replace key, or set a connection proxy. |
| Out of balance | Your provider account holds less than the provider's most expensive task costs. | Top up at the provider. The key is used again once the balance is back. |
| Proxy unreachable | AnySolver cannot reach the provider through the key's connection proxy. | Fix the proxy or change it under Edit. Rechecked with back-off. |
| At its cap | The key reached its total spend cap. | Raise or remove the cap under Edit. A check never clears it. |
| Off | You turned the key off, or every workspace it covered was archived. | Turn on in the key's menu. |
When a key goes from Active or Checking to a problem status, the organization gets a notification in the dashboard bell, seen by members with Own provider keys: Read. The same key and problem notify at most once every 6 hours, so a key that keeps failing and recovering does not flood the bell.
Check again in the key's menu checks the key at once. Replace key swaps the stored key under a fresh encryption and keeps its label, workspaces, caps, spend so far and proxy. The new key is checked at once, unless the key is at its total cap.
Remove stops new tasks at once, lets running tasks finish, and erases the key an hour later. AnySolver's backups taken after that hold nothing of the key. A backup taken before still holds it encrypted, and only AnySolver's encryption keyring opens it.
See which key ran a task
With settings.statistics on, every attempt in getTaskResult of a task that could run on your keys carries keySource, byok or anysolver. On your key it also carries byokKeyId: the key's ID, shown with a copy button when you open the key's Edit dialog on the BYOK page. It stays the same when you rename the key. cost is what AnySolver charged, and fallbacks counts the moves past your keys too. A task whose CapSolver key was out of balance and that finished on AnySolver keys returns:
{
"errorId": 0,
"status": "ready",
"provider": "CapSolver",
"cost": 0.0008,
"solution": { "token": "03AFcWeA6..." },
"retry": {
"totalAttempts": 2,
"retries": 0,
"fallbacks": 1,
"provider": "CapSolver",
"attempts": [
{
"attempt": 0,
"provider": "CapSolver",
"kind": "initial",
"errorCode": "BYOK_KEY_NO_BALANCE",
"errorDescription": "The provider account behind this key has no balance left. Top it up at the provider; the key is used again once the balance is back.",
"durationMs": 312,
"keySource": "byok",
"byokKeyId": "byok_01M7MH3D2DBZ5H3HW45SS6KRDD"
},
{ "attempt": 1, "provider": "CapSolver", "kind": "fallback", "durationMs": 8410, "keySource": "anysolver" }
]
}
}The task details dialog in the dashboard shows the same under Ran on, and lists every attempt under Attempts when a task took more than one: the key each ran on, how long it took and the error that moved the task on. It shows them whatever the request's statistics setting. Without Own provider keys: Read, an attempt on your key reads Own key without its label. Attempts on your keys are left out of provider stats, since your key's balance, IP allow-list and proxy say nothing about the provider.
Errors
Every BYOK_* code has errorId 1, costs nothing, and moves the task on to the next entry in its list when there is one. It does so whatever the Auto Retry and Auto Fallback settings say. For that reason settings.retry.onErrors and settings.fallback.onErrors do not accept them.
BYOK_NO_USABLE_KEY
A task set to only has no usable key. No key of yours covers a provider that supports the task type in the API key's workspace, or every such key is off or in trouble. During an incident AnySolver can also turn own keys off, and the description then says so. createTask refuses such a task before any charge, and a task whose keys stopped being usable after createTask fails with the same code:
{
"errorId": 1,
"errorCode": "BYOK_NO_USABLE_KEY",
"errorDescription": "None of your own provider keys can run this task: add an active key for a provider that supports this task type and this workspace, or allow AnySolver keys with settings.routing.byok \"first\". You are not charged. See https://anysolver.com/docs/getting-started/byok"
}Add a key for a supporting provider, fix the keys listed as in trouble on the BYOK page, or send "byok": "first".
BYOK_KEY_INVALID
The provider rejected your key: invalid, revoked, suspended, or not allowed from the IP AnySolver connected from. The key shows Rejected, with the provider's reason under its status. Replace it, allow the IP at the provider, or set a connection proxy on an allowed IP. A provider that blocks AnySolver's IP for a key without a proxy also ends here (see when a provider blocks an IP).
BYOK_KEY_NO_BALANCE
Your provider account has no balance left. The key shows Out of balance and returns to Active by itself once you top up at the provider.
BYOK_KEY_LIMIT_REACHED
Every own key for this provider reached one of its spend caps. createTask refuses an only task with it when no key has room, and an attempt ends with it when no key can reserve its price. Wait for the period to reset, or raise the cap under Edit.
BYOK_THREAD_LIMIT_REACHED
Every own key for this provider is running as many tasks as its thread limit allows. It ends an attempt of a created task, never createTask itself. With first the task continues on AnySolver keys instead. With only it fails at no charge, and a new task can run once a thread frees. Raise Max threads if your provider plan allows more, add another key, or send "byok": "first".
BYOK_PROXY_FAILED
AnySolver could not reach the provider through the key's connection proxy: no connection within 10 seconds, wrong credentials, or the proxy refused the tunnel. The provider blocking the proxy's IP ends here too. The key shows Proxy unreachable. Check the proxy and its credentials, or change it under Edit. Connection proxy says which failures blame the proxy.
Related
How providers are ranked before your keys move to the front.
How API key and workspace caps count, reset and refuse tasks.
The estimate, settlement and refunds that apply to every task.
Every error code, and which ones retry or fall back by default.
Read your usage and health
What the Overview and Usage pages show about your traffic, which period and scope every number covers, and what each metric means.
Provider Exchange
Contribute idle CapSolver, 2Captcha or Anti-Captcha keys and earn your chosen share of every task they solve, paid as AnySolver balance or crypto.