Grid CAPTCHA

Send separate tile images or one complete grid and get back the selected tile numbers.

Use this for challenges that ask the user to select matching squares from a tiled image.

01 / Prepare

Prepare the input

Choose one input mode: an array of separate tiles, or one image containing the whole grid. For separate tiles, send the top row first, from left to right. A 3 by 3 grid needs exactly 9 images. The instruction describes what the selected tiles must contain.

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

Tile numbering starts at 1 in the top-left tile and moves left to right.
Separate images are assembled left to right, then top to bottom. A returned click value of 1 refers to images[0], 2 to images[1], and so on.
Tiles are fitted into equal square cells without cropping, with white padding when needed. The assembled JPEG is limited to 1000px per side and 600 KB.
You can still send a complete grid using image. The provider receives one assembled image in either mode; returned click indexes are not x/y coordinates.
Use canNoAnswer only when the challenge may genuinely contain no matching tile.

For the complete examples, prepare tile-1.png, tile-2.png, tile-3.png, tile-4.png, tile-5.png, tile-6.png, tile-7.png, tile-8.png, tile-9.png. You can change these filenames in the code.

File encoding & limits

02 / Request

Request parameters

POST/api/v1/captcha/tasks

Send the JSON object directly, without a task wrapper. Set kind to grid. 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 grid.
imagestring: One complete grid as a Base64 JPEG, PNG, or GIF image, or data URL. Up to 600 KB and 1000px on either side. Provide image or images, not both.
imagesstring[]: Alternative to image. Ordered tile images, exactly rows multiplied by columns. Each JPEG, PNG, or GIF may be up to 600 KB and 1000px per side; combined file size must not exceed 3 MB. Base64 and data URLs are supported.
commentstring: Describe which tiles should be selected. Required unless imgInstructions is provided.
imgInstructionsstring: Optional Base64 instruction image or data URL, up to 100 KB. Provide comment, imgInstructions, or both. This is not another grid tile.
rowsintegeroptional: Grid rows. Defaults to 3 and accepts 2 to 6.
columnsintegeroptional: Grid columns. Defaults to 3 and accepts 2 to 6.
minClicksintegeroptional: Minimum selections, 1 to rows multiplied by columns. Default: 1.
maxClicksintegeroptional: Maximum selections, at least minClicks and at most the tile count. Default: rows multiplied by columns.
canNoAnswerbooleanoptional: Allow a No_matching_images answer when no tile matches. Default: false.

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

POST /captcha/tasks

{
  "kind": "grid",
  "images": [
    "BASE64_TILE_1",
    "BASE64_TILE_2",
    "BASE64_TILE_3",
    "BASE64_TILE_4",
    "BASE64_TILE_5",
    "BASE64_TILE_6",
    "BASE64_TILE_7",
    "BASE64_TILE_8",
    "BASE64_TILE_9"
  ],
  "comment": "Select every tile containing a bus.",
  "rows": 3,
  "columns": 3,
  "minClicks": 1,
  "maxClicks": 9,
  "canNoAnswer": false
}

Alternative input

{
  "kind": "grid",
  "image": "BASE64_GRID_IMAGE",
  "comment": "Select every tile containing a bus.",
  "rows": 3,
  "columns": 3
}

Base64 values here are placeholders. The complete examples below encode your local files automatically.

Base URL https://www.scrapingbuddy.com/api/v1

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 result is a list of tile numbers, not pixel coordinates. Numbering starts at 1. With click: [4, 5, 8], choose the first and second cells of row two, and the second cell of row three. Subtract 1 only when looking up an item in a zero-based programming array.

solution.clickinteger[]: One-based tile numbers, left to right and then top to bottom. [4, 5, 8] selects three tiles, not pixel coordinates.
solutionobject: With canNoAnswer enabled, handle a No_matching_images answer as no selection, not a tile index.

123456789

Number tiles from left to right, then top to bottom. A refreshed challenge needs a new task.

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": "grid",
    "status": "ready",
    "solution": {
      "click": [
        4,
        5,
        8
      ]
    },
    "solveCount": 1
  }
}

201 Created / selected fields

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

Task-level failure / HTTP 201 or 200

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

Read the solution / JavaScript

const answer = task.solution.click;
if (Array.isArray(answer)) {
  const selectedTiles = answer.map(tileNumber => images[tileNumber - 1]);
  console.log(selectedTiles);
} else {
  // Handle the no-match answer before selecting a tile.
  console.log(task.solution);
}

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.
Place the input files beside your script, or update the filenames.
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": "grid",
  "comment": "Select every tile containing a bus.",
  "rows": 3,
  "columns": 3,
  "minClicks": 1,
  "maxClicks": 9,
  "canNoAnswer": false
};
body.images = await Promise.all(["tile-1.png","tile-2.png","tile-3.png","tile-4.png","tile-5.png","tile-6.png","tile-7.png","tile-8.png","tile-9.png"].map(encode));

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": "grid",
  "comment": "Select every tile containing a bus.",
  "rows": 3,
  "columns": 3,
  "minClicks": 1,
  "maxClicks": 9,
  "canNoAnswer": false
}''')
body["images"] = [encode(path) for path in ["tile-1.png","tile-2.png","tile-3.png","tile-4.png","tile-5.png","tile-6.png","tile-7.png","tile-8.png","tile-9.png"]]

# 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": "grid",
  "images": [
    "BASE64_TILE_1",
    "BASE64_TILE_2",
    "BASE64_TILE_3",
    "BASE64_TILE_4",
    "BASE64_TILE_5",
    "BASE64_TILE_6",
    "BASE64_TILE_7",
    "BASE64_TILE_8",
    "BASE64_TILE_9"
  ],
  "comment": "Select every tile containing a bus.",
  "rows": 3,
  "columns": 3,
  "minClicks": 1,
  "maxClicks": 9,
  "canNoAnswer": false
}'

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