Quickstart
Base URL https://captcha.browsa.io. Every method is a POST with a JSON body. Your Browsa API key goes in the body as clientKey: the same key and credits as the rest of Browsa.
# 1. Create the task and wait for it in the same call
curl https://captcha.browsa.io/createTask \
-H "Content-Type: application/json" \
-d '{
"clientKey": "'"$BROWSA_API_KEY"'",
"waitSeconds": 25,
"task": {
"type": "AntiTurnstileTaskProxyLess",
"websiteURL": "https://example.com/login",
"websiteKey": "0x4AAAAAAA..."
}
}'
# 2. Still "processing"? Ask again with the taskId
curl https://captcha.browsa.io/getTaskResult \
-H "Content-Type: application/json" \
-d '{"clientKey": "'"$BROWSA_API_KEY"'", "taskId": "TASK_ID", "waitSeconds": 25}'import os
import requests
API = "https://captcha.browsa.io"
KEY = os.environ["BROWSA_API_KEY"]
def call(method, **body):
r = requests.post(f"{API}/{method}", json={"clientKey": KEY, **body}, timeout=40).json()
if r["errorId"]:
raise RuntimeError(r["errorDescription"])
return r
r = call("createTask", waitSeconds=25, task={
"type": "AntiTurnstileTaskProxyLess",
"websiteURL": "https://example.com/login",
"websiteKey": "0x4AAAAAAA...",
})
while r.get("status") != "ready": # each call is held until the task ends, so no sleep
r = call("getTaskResult", taskId=r["taskId"], waitSeconds=25)
print(r["solution"]["token"], r["cost"], r["solveSeconds"])const API = "https://captcha.browsa.io";
async function call(method: string, body: object) {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ clientKey: process.env.BROWSA_API_KEY, ...body }),
});
const r = await res.json();
if (r.errorId) throw new Error(r.errorDescription);
return r;
}
let r = await call("createTask", {
waitSeconds: 25,
task: {
type: "AntiTurnstileTaskProxyLess",
websiteURL: "https://example.com/login",
websiteKey: "0x4AAAAAAA...",
},
});
while (r.status !== "ready") { // each call is held until the task ends, so no sleep
r = await call("getTaskResult", { taskId: r.taskId, waitSeconds: 25 });
}
console.log(r.solution.token, r.cost, r.solveSeconds);{
"errorId": 0,
"taskId": "6f1c0b9e-...",
"status": "ready",
"solution": { "token": "0.AbC...", "type": "turnstile", "userAgent": "Mozilla/5.0 ..." },
"solveSeconds": 6.42,
"cost": { "charged": true, "amount": 0.008, "unit": "credits", "note": "Charged once, for this solve." }
}Every answer is HTTP 200. Read errorId: 0 is fine, 1 is an error.
Methods
| Method | Body | Answer |
|---|---|---|
POST /createTask | clientKey, task, optional waitSeconds | taskId; the solution too when it is ready |
POST /getTaskResult | clientKey, taskId, optional waitSeconds | status: processing, ready with solution, or the task's error |
POST /getBalance | clientKey | balance in credits |
POST /reportCorrectPOST /reportIncorrect | clientKey, taskId | status, outcome |
GET /types | No key | The task types |
GET /errors | No key | Every error code |
GET /health | No key | Service state |
createTask
Picture tasks are answered in this call. Token tasks return a taskId; add waitSeconds to get the solution in the same call when it is ready in time.
curl https://captcha.browsa.io/createTask \
-H "Content-Type: application/json" \
-d '{
"clientKey": "'"$BROWSA_API_KEY"'",
"task": {
"type": "ImageToTextTask",
"body": "BASE64_OF_THE_PICTURE"
}
}'import os
import requests
r = requests.post(
"https://captcha.browsa.io/createTask",
json={
"clientKey": os.environ["BROWSA_API_KEY"],
"task": {
"type": "ImageToTextTask",
"body": "BASE64_OF_THE_PICTURE"
},
},
)
print(r.json())const r = await fetch("https://captcha.browsa.io/createTask", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
clientKey: process.env.BROWSA_API_KEY,
task: {
"type": "ImageToTextTask",
"body": "BASE64_OF_THE_PICTURE"
},
}),
});
console.log(await r.json());{
"errorId": 0,
"taskId": "0d6a4c1e-...",
"status": "ready",
"solution": { "text": "W9H5K" },
"solveSeconds": 2.9,
"cost": { "charged": true, "amount": 0.004, "unit": "credits", "note": "Charged once, for this solve." }
}getTaskResult
Results are kept for 10 minutes after the solve.
curl https://captcha.browsa.io/getTaskResult \
-H "Content-Type: application/json" \
-d '{
"clientKey": "'"$BROWSA_API_KEY"'",
"taskId": "TASK_ID",
"waitSeconds": 25
}'import os
import requests
r = requests.post(
"https://captcha.browsa.io/getTaskResult",
json={
"clientKey": os.environ["BROWSA_API_KEY"],
"taskId": "TASK_ID",
"waitSeconds": 25,
},
)
print(r.json())const r = await fetch("https://captcha.browsa.io/getTaskResult", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
clientKey: process.env.BROWSA_API_KEY,
taskId: "TASK_ID",
waitSeconds: 25,
}),
});
console.log(await r.json());getBalance
curl https://captcha.browsa.io/getBalance \
-H "Content-Type: application/json" \
-d '{
"clientKey": "'"$BROWSA_API_KEY"'"
}'import os
import requests
r = requests.post(
"https://captcha.browsa.io/getBalance",
json={
"clientKey": os.environ["BROWSA_API_KEY"],
},
)
print(r.json())const r = await fetch("https://captcha.browsa.io/getBalance", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
clientKey: process.env.BROWSA_API_KEY,
}),
});
console.log(await r.json());{ "errorId": 0, "balance": 96.412, "unit": "credits" }Wait in one call
waitSeconds on createTask or getTaskResult holds the call until the task ends, up to 25 seconds. A larger number is cut to 25.
- Ended in time:
status: "ready"with the solution, or the task's error. - Not yet:
status: "processing". CallgetTaskResultagain; no sleep needed between calls. - Without
waitSecondsboth methods answer at once, and you poll.
Cost and time
Every task answer has cost and solveSeconds. Failed solves are free. A solve is charged once, when it is solved.
{
"errorId": 1,
"errorCode": "ERROR_CAPTCHA_UNSOLVABLE",
"errorDescription": "The solver could not solve this captcha. Send a new task; ... You were not charged.",
"fix": "Send a new task; ...",
"charged": false,
"taskId": "6f1c0b9e-...",
"status": "failed",
"cost": { "charged": false, "amount": 0, "unit": "credits", "note": "Nothing was charged: a failed solve is free." }
}unit is credits. Prices per type are in the type table.
Report a result
Tell the API whether the site took the solution. Reports are recorded and used to improve solving.
curl https://captcha.browsa.io/reportIncorrect \
-H "Content-Type: application/json" \
-d '{
"clientKey": "'"$BROWSA_API_KEY"'",
"taskId": "TASK_ID"
}'import os
import requests
r = requests.post(
"https://captcha.browsa.io/reportIncorrect",
json={
"clientKey": os.environ["BROWSA_API_KEY"],
"taskId": "TASK_ID",
},
)
print(r.json())const r = await fetch("https://captcha.browsa.io/reportIncorrect", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
clientKey: process.env.BROWSA_API_KEY,
taskId: "TASK_ID",
}),
});
console.log(await r.json());/reportCorrectwhen the site accepted it,/reportIncorrectwhen it refused it.- One report per task, within 15 minutes of the solve.
Task types
18 types are live: 7 answer a picture inside createTask, 11 return a token or cookie. The same list, with optional parameters and solution fields, is at GET /types (no key).
| Type | Solves | Required | Solution | Per 1,000 solves |
|---|---|---|---|---|
ImageToTextTask | Image text (picture) | body or images | text, answers | 4 credits ($0.40) |
ReCaptchaV2Classification | reCAPTCHA v2 grid classification (picture) | image, question | type, objects, hasObject, size | 10 credits ($1.00) |
AwsWafClassification | AWS WAF grid classification (picture) | images, question | objects | 10 credits ($1.00) |
GeeTestSlide | GeeTest slide (picture) | version, imageBackground, imageFull (v3), imageSlice (v4), top (v4), bgCssWidth (v4) | distance, x | 8 credits ($0.80) |
TextCaptchaTask | Question in words (picture) | comment | text, alternatives | 4 credits ($0.40) |
BoundingBoxTask | Box around an object (picture) | body, comment | bounding_boxes | 10 credits ($1.00) |
DragDropTask | Drag pieces into the picture (picture) | body, pieces | coordinates, centers | 10 credits ($1.00) |
AntiTurnstileTaskProxyLessAntiTurnstileTask with your proxy | Cloudflare Turnstile token | websiteURL, websiteKey; proxy (AntiTurnstileTask) | token, type, userAgent | 8 credits ($0.80) |
ReCaptchaV3TaskProxyLessReCaptchaV3Task with your proxy | reCAPTCHA v3 token | websiteURL, websiteKey; proxy (ReCaptchaV3Task) | gRecaptchaResponse, userAgent, createTime | 8 credits ($0.80) |
ReCaptchaV3EnterpriseTaskProxyLessReCaptchaV3EnterpriseTask with your proxy | reCAPTCHA v3 Enterprise token | websiteURL, websiteKey; proxy (ReCaptchaV3EnterpriseTask) | gRecaptchaResponse, userAgent, createTime | 12 credits ($1.20) |
ReCaptchaV2TaskProxyLessReCaptchaV2Task with your proxy | reCAPTCHA v2 token | websiteURL, websiteKey; proxy (ReCaptchaV2Task) | gRecaptchaResponse, userAgent, createTime | 10 credits ($1.00) |
ReCaptchaV2EnterpriseTaskProxyLessReCaptchaV2EnterpriseTask with your proxy | reCAPTCHA v2 Enterprise token | websiteURL, websiteKey; proxy (ReCaptchaV2EnterpriseTask) | gRecaptchaResponse, userAgent, createTime | 12 credits ($1.20) |
AntiCloudflareTaskneeds your proxy | Cloudflare full-page check | websiteURL, proxy | cookies, token, type, userAgent | 12 credits ($1.20) |
Read from GET https://captcha.browsa.io/types on 2026-11-21. Dollar figures are at $0.10 a credit, the Starter pack; larger packs cost less per credit. Names are case-sensitive.
curl https://captcha.browsa.io/typesimport requests
for t in requests.get("https://captcha.browsa.io/types").json()["types"]:
print(t["type"], t["status"], t["price"]["creditsPerSolve"], [p["name"] for p in t["required"]])const { types } = await (await fetch("https://captcha.browsa.io/types")).json();
for (const t of types) {
console.log(t.type, t.status, t.price.creditsPerSolve, t.required.map((p) => p.name));
}Proxy. "http://user:pass@host:port" or "http:host:port:user:pass". The fields proxyType, proxyAddress, proxyPort, proxyLogin, proxyPassword are accepted instead.
How often does each captcha pass? Measured per captcha type, with a demo and a log of each: captcha results.
Errors
An error is HTTP 200 with errorId: 1, errorCode, errorDescription, fix and charged. No error is charged.
{
"errorId": 1,
"errorCode": "ERROR_ZERO_BALANCE",
"errorDescription": "not enough credits. Buy credits at https://app.browsa.io/dashboard/credits, then retry. You were not charged.",
"fix": "Buy credits at https://app.browsa.io/dashboard/credits, then retry.",
"charged": false
}| Code | Meaning | What to fix | Retry |
|---|---|---|---|
ERROR_BAD_REQUEST | The request could not be read. | Send a POST with a JSON object as the body to one of the documented methods. | After the fix |
ERROR_KEY_DENIED_ACCESS | The key is missing, wrong, revoked, or its workspace may not solve. | Send your Browsa API key (agt_live_...) as clientKey; the description says which rule refused it. | After the fix |
ERROR_KEY_TEMP_BLOCKED | A daily, hourly or per-site limit is reached. | Wait for the limit named in the description to reset, or ask support@browsa.io for a higher one. | Later |
ERROR_RATE_LIMIT | Too many requests for this key in the last minute. | Slow down and retry in a few seconds. | Later |
ERROR_ZERO_BALANCE | The workspace does not have enough credits for this solve. | Buy credits at https://app.browsa.io/dashboard/credits, then retry. | After the fix |
ERROR_BUDGET_EXCEEDED | The workspace's monthly spending limit is reached. | Raise the monthly limit in the dashboard, or wait for the 1st of next month (UTC). | After the fix |
ERROR_TASK_NOT_SUPPORTED | The task type is not a type this API accepts, or it is switched off. | Use a type name exactly as GET /types lists it, with status live. | After the fix |
ERROR_INVALID_TASK_DATA | A task parameter is missing or has a wrong value. | Fix the parameter the description names; GET /types lists each type's parameters. | After the fix |
ERROR_UNKNOWN_QUESTION | The question of a grid classification task is not one this API knows. | Send the question as the challenge gives it (a /m/... id or plain words; aws:grid:<object> for AWS WAF). | After the fix |
ERROR_PARSE_IMAGE_FAIL | The image is not valid base64 or is empty. | Send the raw file bytes encoded as base64 (a data: URL is accepted). | After the fix |
ERROR_INVALID_IMAGE | The image is too large, or not a JPEG, PNG, GIF or WebP. | Send the picture as the captcha serves it, under the size the description names. | After the fix |
ERROR_TASKID_INVALID | No such task for this key, or its result has expired. | Send the taskId createTask returned, with the same key, within 10 minutes of the solve. | After the fix |
ERROR_CAPTCHA_UNSOLVABLE | The solver could not solve this captcha. | Send a new task; when it keeps failing for one site, check websiteURL and websiteKey against the live widget. | Right away |
ERROR_TASK_TIMEOUT | The task did not finish in time. | Send a new task. | Right away |
ERROR_SERVICE_UNAVALIABLE | The service could not take or finish the task right now. | Retry in a few seconds; https://captcha.browsa.io/health shows the state. | Later |
ERROR_REPORT_NOT_SOLVED | Only a solved task can be reported. | Nothing to do: a task that failed or is still running was never charged. | After the fix |
ERROR_REPORT_TOO_LATE | The solve is older than the report window. | Report a solution within 15 minutes of the solve. | After the fix |
ERROR_ALREADY_REPORTED | This solve was already reported. | Nothing to do: the first report stands. | After the fix |
ERROR_REPORT_LIMIT | This workspace has reported too large a share of its recent solves as incorrect. | Check how the solutions are submitted (expired tokens, a different user agent or address); write to support@browsa.io with task ids when the solutions really are wrong. | Later |
Read from GET https://captcha.browsa.io/errors on 2026-11-21. A result that has expired was charged when it was solved.
Limits and fair use
| Limit | Value | Past it |
|---|---|---|
| New tasks per key | 60 a minute | ERROR_RATE_LIMIT |
| Tasks per workspace | 300 an hour, 3,000 a day | ERROR_KEY_TEMP_BLOCKED |
| Tasks for one site | 2,000 a day | ERROR_KEY_TEMP_BLOCKED |
| Monthly spending limit | The one set for your workspace | ERROR_BUDGET_EXCEEDED |
Longest waitSeconds | 25 seconds | Cut to the longest |
| Calls held at once | 200 per workspace | Answered at once |
| Result kept | 10 minutes | ERROR_TASKID_INVALID |
| Reports | One per task, within 15 minutes; 60 a minute per key | ERROR_REPORT_TOO_LATE, ERROR_RATE_LIMIT |
Days are UTC. Need more? Write to support@browsa.io.
Free trial
A new account can try 25 solves, up to 10 a day, before buying credits. No card. Failed solves do not count.
- Trial solves are paid from your free signup credits. Verify your email first.
- After the trial, buy credits; any pack works.
Client libraries
This is the createTask / getTaskResult format that common captcha client libraries use. A library that lets you set its server address works with https://captcha.browsa.io and your Browsa key.
getBalanceanswers in credits, with"unit": "credits".minScoreis accepted and not guaranteed;enterprisePayloadis accepted and ignored.waitSeconds,cost,solveSeconds,fixandchargedare additions. A client that ignores them works as before.