Text CAPTCHA

Send a plain text question and get back the answer text.

Use this for human-readable questions, riddles, or text-only challenges that do not require an image upload.

01 / Prepare

Prepare the input

Put the complete written question in comment. No image or file upload is needed. Make the expected answer unambiguous and include any context needed to answer the question.

Each task reserves $0.015 from your wallet. Successful tasks cost 1.5 times the provider cost; unused reserved credit is returned. Failed tasks are not charged. Billing details

Include all context needed to answer the question.
Keep the wording short and direct.
Do not include private account data or credentials in the question text.

File encoding & limits

02 / Request

Request parameters

POST/api/v1/captcha/tasks

Send the JSON object directly, without a task wrapper. Set kind to text. All fields below belong to the JSON body.

Required headers

Authorizationstringrequired: Bearer followed by your ScrapingBuddy API key. Keep it on your server.
Content-Typestringrequired: application/json.
Idempotency-KeyUUID v4required: Retain one generated UUID per new task. Do not submit the same task concurrently.

Authentication guide

kindstringrequired: Always text.
commentstringrequired: The complete question, 1 to 1000 characters after trimming. No image is needed.

Decoded file limits use 1 KB = 1,000 bytes. The complete JSON payload must fit within 5,000,000 bytes after Base64 encoding.

03 / Result

Understand the result

Creation returns HTTP 201. Fetching the task returns HTTP 200. Both wrap the task in task; always check its status before reading the solution.

The returned solution.text is the answer, not a copy of your question. Keep it as text unless your application has a separate, explicit conversion rule. An accepted request may still end in a failed task if the question cannot be solved.

solution.textstring: Answer to your question, not an echo of comment. Preserve the returned text rather than coercing it to a number.

Shared task fields

idUUID: Save this ID to fetch the task or contact support.
statusstring: submitting or processing: wait. ready: use solution. failed: stop and read the error.
solutionobject | null: Null until a result is available. The shape depends on the CAPTCHA type.
errorCode / errorDescriptionstring | null: Task failure details. A failed task can still arrive with HTTP 200 or 201.
coststring | null: Provider-reported USD cost; not the customer debit.
chargedecimal string: Actual customer charge in USD: provider cost multiplied by 1.5. Zero before settlement or for legacy tasks.
billingStatusstring: reserved, charged, released, awaiting_credit, review, or legacy. A review requires support; awaiting_credit needs a top-up.
solveCountnumber | null: Provider-reported solving attempts when available.
createdAt / updatedAt / completedAttimestamp | null: Task timestamps; completedAt is null until the task has finished.
comment / requestMetastring / object: Saved instructions and input metadata. Raw files are not returned.

200 OK / selected fields

{
  "task": {
    "id": "11111111-1111-4111-8111-111111111111",
    "kind": "text",
    "status": "ready",
    "solution": {
      "text": "friday"
    },
    "solveCount": 1
  }
}

201 Created / selected fields

{
  "task": {
    "id": "11111111-1111-4111-8111-111111111111",
    "kind": "text",
    "status": "processing",
    "solution": null
  }
}

Task-level failure / HTTP 201 or 200

{
  "task": {
    "id": "11111111-1111-4111-8111-111111111111",
    "kind": "text",
    "status": "failed",
    "solution": null,
    "errorCode": "ERROR_CAPTCHA_UNSOLVABLE",
    "errorDescription": "Captcha task could not be solved."
  }
}

Read the solution / JavaScript

const answer = task.solution.text;
console.log(answer); // For "What is seven plus two?", an answer may be "9".

04 / Integrate

Complete examples

These Node.js and Python scripts prepare the input, create one task and poll until it is ready or failed. They stop waiting after approximately 3 minutes. A client timeout does not cancel the task.

Set SCRAPINGBUDDY_API_KEY in your server environment.
Replace the sample question or site values with your own challenge.
For Node.js, use version 20+ and save as solve.mjs. For Python, install requests and save as solve.py.
Run the script and retain the printed request and task IDs.

cURL shows task creation only. Use the GET example to retrieve its result.

solve.mjs / node solve.mjs

// Node.js 20+. Run: node solve.mjs
import { readFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";

const base = "https://www.scrapingbuddy.com/api/v1";
if (!process.env.SCRAPINGBUDDY_API_KEY) throw new Error("Set SCRAPINGBUDDY_API_KEY.");
const auth = { Authorization: "Bearer " + process.env.SCRAPINGBUDDY_API_KEY };
const encode = async (path) => (await readFile(path)).toString("base64");
const body = {
  "kind": "text",
  "comment": "If tomorrow is Saturday, what day is today?"
};


async function api(path, options = {}) {
  const response = await fetch(base + path, {
    ...options,
    headers: { ...auth, "Content-Type": "application/json", ...options.headers },
    signal: AbortSignal.timeout(30000),
  });
  const data = await response.json().catch(() => ({}));
  if (!response.ok) throw new Error(response.status + ": " + (data.error || response.statusText)
    + "; Retry-After: " + response.headers.get("Retry-After"));
  return data;
}

// Retain this ID; never retry POST concurrently or automatically after a timeout.
const requestId = randomUUID();
console.log("Request ID:", requestId);
const created = await api("/captcha/tasks", {
  method: "POST",
  headers: { "Idempotency-Key": requestId },
  body: JSON.stringify(body)
});

let task = created.task;
console.log("Task ID:", task.id);
const deadline = Date.now() + 180_000;
while (task.status === "submitting" || task.status === "processing") {
  if (Date.now() >= deadline) throw new Error("Still processing. Resume GET polling for " + task.id);
  await new Promise((resolve) => setTimeout(resolve, 6000));
  task = (await api("/captcha/tasks/" + task.id, { headers: {} })).task;
}

if (task.status !== "ready") throw new Error(task.errorCode + ": " + task.errorDescription);
console.log(task.solution);

solve.py / python solve.py

# Python 3. Install: pip install requests. Run: python solve.py
import base64, json, os, time, uuid, requests
from pathlib import Path

BASE = "https://www.scrapingbuddy.com/api/v1"
auth = {"Authorization": "Bearer " + os.environ["SCRAPINGBUDDY_API_KEY"]}
def encode(path):
    return base64.b64encode(Path(path).read_bytes()).decode("ascii")

body = json.loads(r'''{
  "kind": "text",
  "comment": "If tomorrow is Saturday, what day is today?"
}''')


# Retain this ID; do not automatically retry POST after a timeout.
request_id = str(uuid.uuid4())
print("Request ID:", request_id)

response = requests.post(
    BASE + "/captcha/tasks",
    json=body,
    headers={**auth, "Content-Type": "application/json", "Idempotency-Key": request_id},
    timeout=30,
)
response.raise_for_status()
task = response.json()["task"]
print("Task ID:", task["id"])
deadline = time.monotonic() + 180

while task["status"] in ("submitting", "processing"):
    if time.monotonic() >= deadline:
        raise TimeoutError("Still processing. Resume GET polling for " + task["id"])
    time.sleep(6)
    poll = requests.get(BASE + "/captcha/tasks/" + task["id"], headers=auth, timeout=30)
    poll.raise_for_status()
    task = poll.json()["task"]

if task["status"] != "ready":
    raise RuntimeError(f"{task.get('errorCode')}: {task.get('errorDescription')}")
print(task["solution"])

Bash / create request only

# Keep your secret in an environment variable.
export SCRAPINGBUDDY_API_KEY="YOUR_API_KEY"

# Bash. Replace sample Base64 values before sending.
# Generate and retain one UUID v4 per new task; do not retry concurrently.
export TASK_IDEMPOTENCY_KEY="$(uuidgen)"

curl -X POST "https://www.scrapingbuddy.com/api/v1/captcha/tasks" \
  -H "Authorization: Bearer $SCRAPINGBUDDY_API_KEY" \
  -H "Idempotency-Key: $TASK_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "text",
  "comment": "If tomorrow is Saturday, what day is today?"
}'

When something goes wrong

Check whether you received an HTTP error or a task with status: failed. Fix validation errors before retrying. For HTTP 429, pause for Retry-After; all requests share the account limit of 60 per minute.

If creation times out, do not automatically submit another task. Keep your request ID and check the existing task or Usage first.

Errors & troubleshooting Polling & safe retries Contact support