How to Handle Queue-it BotDeflector CAPTCHA with curl and Python

This hands-on tutorial begins at the request boundary. You will create and poll AntiBotdeflectorTaskProxyLess, read solution.token, and then compare that asynchronous flow with the direct VisionEngine response that carries solution.points. Every request uses placeholders so no API key or live challenge value is exposed.

TL;DR

• When you code a current Queue-it CAPTCHA integration, treat it as BotDeflector workflows, not as plain text recognition.
• Reach for AntiBotdeflectorTaskProxyLess once you have the page URL, BotDeflector domain, and challenge flowToken; the asynchronous result is returned in solution.token.
• Switch to VisionEngine with module: "botdeflector" only for a visual challenge that provides foreground and background images; this request returns recognition coordinates directly.
• websiteURL and domain are separate BotDeflector fields and may contain different hostnames. Capture both from the authorized browser session.
• Do not close or replace the Queue-it browser session during the request because the returned result belongs to the challenge context that produced the inputs.
• Use this workflow only on Queue-it implementations you own, test, or have explicit permission to automate.

Queue-it virtual waiting rooms control access during traffic spikes such as ticket releases, product launches, and limited-inventory events. The CAPTCHA step used in current integrations is more than a picture containing characters: BotDeflector supplies a challenge flow that can require either a token result or visual coordinates.

This updated guide explains both supported paths with CapSolver. The token path is the default integration for a captured flowToken; the VisionEngine path applies when the browser exposes the corresponding foreground and background challenge images. CapSolver's CAPTCHA API documentation guide explains the shared task lifecycle and error model.

Understand the two request shapes before coding

Before writing curl, think of the Queue-it flow as BotDeflector rather than a standalone OCR form. A BotDeflector challenge contains session-bound inputs, and the expected output depends on the integration path:

Path	CapSolver task	Required challenge data	Result
Token mode	AntiBotdeflectorTaskProxyLess	websiteURL, domain, flowToken	solution.token after polling
Visual recognition mode	VisionEngine with module: "botdeflector"	image, imageBackground, websiteURL	solution.points in the createTask response

You cannot swap the payloads or outputs between these modes. Token mode does not accept a Base64 image as a substitute for flowToken, while visual recognition mode does not return the final BotDeflector token. Inspect the challenge implementation in your authorized browser session and choose the path matching the data available there.

Queue-it's traffic waiting room and the CAPTCHA solver also use different queues. The waiting room determines when a visitor may continue, while the CapSolver API processes a challenge task. The request queue glossary provides useful background for separating application queueing from API task polling.

Quick check: if your code is looking for recognized text, stop. This integration returns either solution.token or solution.points.

Set up an authorized test session

Gather these items before running the examples:

• A CapSolver API key stored in an environment variable or secrets manager.
• A Queue-it page and BotDeflector challenge that you are authorized to test.
• The exact page URL where the challenge appears.
• For token mode: the BotDeflector domain and current flowToken captured from the same browser session.
• For visual mode: Base64-encoded foreground and background challenge images.
• An HTTP client that can send JSON requests to https://api.capsolver.com.

Do not place a production API key directly in source code. The examples use YOUR_API_KEY, FLOW_TOKEN_FROM_PAGE, and example domains as placeholders.

Walk through token mode with curl

Token mode uses AntiBotdeflectorTaskProxyLess, then polls getTaskResult until CapSolver returns solution.token. The field names and response shape follow the current BotDeflector token-mode documentation.

Step 1: Capture the BotDeflector inputs

Pull all three values from the exact same authorized browser session:

• websiteURL: the full page URL where the BotDeflector challenge is running.
• domain: the BotDeflector domain required by that challenge.
• flowToken: the current challenge token exposed by the BotDeflector flow.

Do not guess that domain is simply the hostname from websiteURL. The official task definition treats them as separate inputs, and they may not use the same domain name.

Step 2: Create the token task

Put the captured values into createTask:

curl --request POST 'https://api.capsolver.com/createTask' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientKey": "YOUR_API_KEY",
    "task": {
      "type": "AntiBotdeflectorTaskProxyLess",
      "websiteURL": "https://queue.example.com/waitingroom/",
      "domain": "challenge.example.net",
      "flowToken": "FLOW_TOKEN_FROM_PAGE"
    }
  }'

The happy-path response includes a task ID:

{
  "errorId": 0,
  "errorCode": "",
  "errorDescription": "",
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}

Check errorId before storing taskId. If task creation fails, log errorCode and errorDescription without recording the API key or full challenge token.

Step 3: Poll for the BotDeflector token

Send the returned task ID to getTaskResult:

curl --request POST 'https://api.capsolver.com/getTaskResult' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientKey": "YOUR_API_KEY",
    "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
  }'

Poll with a deadline while the response status is processing. Stop immediately if the API returns a nonzero errorId or a failed status. When the task is ready, read the token from solution.token:

{
  "errorId": 0,
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006",
  "status": "ready",
  "solution": {
    "token": "BOTDEFLECTOR_TOKEN"
  }
}

Step 4: Return the token to the same browser flow

Send the token back to the BotDeflector integration point used by the same Queue-it browser session. Do not create a fresh browser context between capturing flowToken and applying the result. Session changes, navigation, or challenge refreshes can invalidate the context and require a new task.

The exact injection or submission point belongs to the Queue-it implementation you are testing. Capture it from your own application integration instead of relying on a universal selector.

Redeem Your CapSolver Bonus Code

Boost your automation budget instantly!
Use bonus code CAP26 when topping up your CapSolver account to get an extra 5% bonus on every recharge — with no limits.
Redeem it now in your CapSolver Dashboard

Turn the curl flow into a reusable Python function

The Python version below creates a BotDeflector task, polls with a bounded timeout, and returns solution.token. It uses placeholder challenge values because a real flowToken must come from your authorized browser session.

import os
import time

import requests


API_BASE = "https://api.capsolver.com"
API_KEY = os.environ["CAPSOLVER_API_KEY"]


def solve_botdeflector(website_url, domain, flow_token, timeout=120):
    create_response = requests.post(
        f"{API_BASE}/createTask",
        json={
            "clientKey": API_KEY,
            "task": {
                "type": "AntiBotdeflectorTaskProxyLess",
                "websiteURL": website_url,
                "domain": domain,
                "flowToken": flow_token,
            },
        },
        timeout=30,
    )
    create_response.raise_for_status()
    created = create_response.json()

    if created.get("errorId"):
        raise RuntimeError(
            f"createTask failed: {created.get('errorCode')} - "
            f"{created.get('errorDescription')}"
        )

    task_id = created["taskId"]
    deadline = time.monotonic() + timeout

    while time.monotonic() < deadline:
        time.sleep(2)
        result_response = requests.post(
            f"{API_BASE}/getTaskResult",
            json={"clientKey": API_KEY, "taskId": task_id},
            timeout=30,
        )
        result_response.raise_for_status()
        result = result_response.json()

        if result.get("errorId"):
            raise RuntimeError(
                f"getTaskResult failed: {result.get('errorCode')} - "
                f"{result.get('errorDescription')}"
            )

        if result.get("status") == "ready":
            return result["solution"]["token"]

        if result.get("status") == "failed":
            raise RuntimeError("BotDeflector task failed")

    raise TimeoutError(f"BotDeflector task {task_id} exceeded {timeout}s")


token = solve_botdeflector(
    website_url="https://queue.example.com/waitingroom/",
    domain="challenge.example.net",
    flow_token="FLOW_TOKEN_FROM_PAGE",
)
print(token)

For more detail on environment variables, request handling, and reusable client structure, see the Python CAPTCHA API integration guide.

Handle the visual coordinate mode

Only use VisionEngine when the challenge exposes the visual assets required by the BotDeflector recognition module. This path accepts a foreground image and an imageBackground, then returns click coordinates in the initial createTask response.

The request uses type: "VisionEngine" and module: "botdeflector":

curl --request POST 'https://api.capsolver.com/createTask' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientKey": "YOUR_API_KEY",
    "task": {
      "type": "VisionEngine",
      "module": "botdeflector",
      "image": "BASE64_FOREGROUND_IMAGE",
      "imageBackground": "BASE64_BACKGROUND_IMAGE",
      "websiteURL": "https://queue.example.com/waitingroom/"
    }
  }'

According to the current VisionEngine documentation, this task returns recognition data directly; it does not require a separate getTaskResult request. A successful response has this shape:

{
  "errorId": 0,
  "errorCode": "",
  "errorDescription": "",
  "status": "ready",
  "solution": {
    "points": [[123, 88], [244, 84], [174, 70]]
  },
  "taskId": "TASK_ID"
}

Click the returned points in the visual challenge in the same coordinate space as the submitted images. Scaling, cropping, or using a screenshot with different dimensions can move the target positions and cause incorrect interactions.

VisionEngine handles the recognition step; it does not replace the surrounding browser state management. If the page expects a subsequent token exchange, continue that exchange inside the same authorized session.

Troubleshoot the code and browser handoff

The task is created but never becomes ready

Double-check that the flowToken is current and belongs to the same page session. Also verify that websiteURL and domain were captured independently rather than constructed from one hostname. Use bounded polling and stop on API errors instead of looping indefinitely.

The returned token is rejected

When a token is rejected, the likely issue is that the page state changed after the challenge inputs were captured. Keep cookies, browser context, URL, and challenge state stable until the result is applied. If the challenge refreshes, capture a new flowToken and create a new task.

VisionEngine returns points but the clicks miss

Send the original challenge images without resizing them, and apply the coordinates against the same dimensions. Check whether your browser automation introduced device-pixel-ratio scaling, CSS resizing, or a cropped screenshot.

The integration works in a script but fails in CI

Compare browser versions, viewport settings, timing, cookies, and secret availability between local and CI environments. For a wider testing checklist, see CAPTCHA handling in automated QA.

Keep the test lawful and bounded

Use this Queue-it and BotDeflector workflow only on systems you own, QA environments you operate, or workflows for which the site owner has granted explicit permission. A CAPTCHA-solving API does not grant access rights or override a site's terms, queue rules, rate limits, or authorization requirements.

Keep test volume bounded, avoid high-demand public events unless they are part of an approved test, and log only the minimum diagnostic data. API keys, cookies, flowToken values, and returned tokens should be treated as secrets and excluded from screenshots, analytics, and long-term logs.

What to implement next

Queue-it CAPTCHA handling now requires a BotDeflector-aware integration. Use AntiBotdeflectorTaskProxyLess for the session token flow and read the result from solution.token; use VisionEngine with the botdeflector module only when the challenge supplies the foreground and background images needed for coordinate recognition.

The rule worth carrying into your own code is to preserve the original browser context from challenge capture through result submission. For authorized Queue-it testing, CapSolver provides both documented BotDeflector paths through the same task API.

FAQ

Q: What task type should I use for Queue-it BotDeflector token mode?

Reach for AntiBotdeflectorTaskProxyLess once you have websiteURL, domain, and a current flowToken. Poll getTaskResult and read the completed value from solution.token.

Q: Does Queue-it BotDeflector token mode require a CAPTCHA image?

No. The token-mode task uses the page URL, BotDeflector domain, and flowToken. If the challenge instead exposes a foreground image and background image for visual recognition, use the separate VisionEngine path.

Q: When should I use the VisionEngine botdeflector module?

Switch to VisionEngine with module: "botdeflector" for the visual recognition step that supplies image and imageBackground. The API returns solution.points directly in the createTask response.

Q: Why can the BotDeflector domain differ from the Queue-it page URL?

BotDeflector defines websiteURL and domain as separate task fields, so the challenge service may use a hostname different from the visible Queue-it page. Capture both values from the active integration.

Q: Can I reuse a returned BotDeflector token in another browser session?

No reuse should be assumed. Apply the token to the same authorized browser flow that produced the challenge inputs; if the page or challenge refreshes, capture new inputs and create a new task.

Q: Is automated Queue-it CAPTCHA handling permitted?

It is appropriate only when you own the system or have explicit authorization to test or automate it. Respect the site's terms, access controls, queue policies, rate limits, and applicable law.