Your first task

Pricing & wallet credit

Dashboard tests and API tasks use the same paid service. Each new task reserves $0.015 from your shared wallet before submission. You need at least this much available credit. The reserve is not a fixed price: a successful task costs 1.5 times the actual provider cost. For example, $0.0012 becomes $0.0018; $0.01 becomes $0.015.

When the task finishes, the reservation is released and the exact final charge is recorded once. Confirmed failed tasks return the reservation in full. A provider timeout does not prove failure: credit remains reserved until the result is confirmed. If billingStatus is review, contact support with the task ID. If it is awaiting_credit, top up to receive the saved answer without creating another task.

GET /api/v1/balance returns balanceUsd as an exact USD decimal string. Store money as decimal values, not binary floating-point. balanceCents remains available, rounded down to whole cents. New billing does not apply retroactively to legacy tasks.

1. Prepare your API key

Sign in to ScrapingBuddy and create an API key in Profile > API access. Keep it on your server. This is your ScrapingBuddy key, not a key from a solver provider.

These examples use Bash and cURL. Replace YOUR_API_KEY with your own key in your local environment. Never commit the key to Git or paste it into public logs. Requests create real tasks; these examples are not a free sandbox.

export SCRAPINGBUDDY_API_KEY="YOUR_API_KEY"

2. Create a task

A task is one question or challenge that you want solved. Send a JSON body to the create endpoint. The kind field tells the API which solution to use.

Generate a UUID v4 for Idempotency-Key and keep it with your request. Use a new UUID for a genuinely new task. The example question goes in comment; do not wrap the body inside a task property.

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":"What is seven plus two?"}'

3. Save the ID and check the status

The response contains a task object. Save task.id. If task.status is processing, the request was accepted but the answer is not ready yet. Wait about 6 seconds, then fetch the same task.

Replace TASK_ID below with the returned ID. Repeat the GET request every 5 to 10 seconds while the task is processing. Do not send another POST just to check progress.

curl "https://www.scrapingbuddy.com/api/v1/captcha/tasks/TASK_ID" \
  -H "Authorization: Bearer $SCRAPINGBUDDY_API_KEY"

4. Read the answer

When task.status is ready, read task.solution. For this text question, solution.text is the answer. Keep it as a string.

If the status is failed, stop polling and inspect errorCode and errorDescription. An HTTP 200 or 201 alone does not mean the challenge was solved. The example below shows selected fields, not every field in the response.

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

Choose your CAPTCHA type

You now know the shared create-and-poll flow. Choose a solution in API reference to see its inputs and answer format. Image, audio and puzzle tasks use the same endpoints, but their request bodies are different.

Each solution includes complete Node.js and Python examples that prepare the input, create one task and poll with a finite timeout.