Fetch a current, real-world (Windows) User-Agent string from CapMonster's UA service.

Use ONE User-Agent as a single fingerprint thread across the whole solve — they must all match or the solved token is likely to be rejected:

1. set it as the patchright browser context's UA (browser-launch flag / device emulation), so the page is loaded with it;

2. pass the SAME string as the userAgent field of any CapMonster task that accepts one (reCAPTCHA, Turnstile/Cloudflare, FunCaptcha, AWS WAF, DataDome, Imperva, Yidun, TenDI, …);

3. when the solution comes back with its own userAgent (or headers["User-Agent"]), the token is bound to THAT value — reuse it for the injection and any follow-up requests instead of your original.

CapMonster requires a current Windows-OS UA; a stale/invalid one fails with ERROR_WRONG_USERAGENT, so re-fetch here rather than reusing an old one.

Submit a captcha task; returns taskId. Poll with get_task_result.

task must include 'type' and all required fields. Always look up required params at https://docs.capmonster.cloud/docs/captchas/ — do not rely on training data.

For a task holding one or more large base64 blobs (ComplexImageTask with several images, htmlPageBase64 for Cloudflare cf_clearance/wait_room, or any other opaque field/combined payload too big to type safely) pass task_file instead of task: the path to a JSON file, on this machine's filesystem, containing the exact task object. Write that file with a script or a browser-side save (never by hand-typing a long base64 literal into this tool call's own arguments — a single dropped/unclosed quote in a multi-KB string silently merges what should be separate array elements into one, which is why this exists: a 9-image ComplexImageTask sent inline this way became "Image count: 1, but the task supports: 9" even though the array had 9 entries when written). Provide exactly one of task or task_file.

Fetch a task result ONCE (a single poll).

Prefer get_task_result_wait, which polls for you. Use this only if you want to drive the poll loop yourself.

Returns a dict:

• while solving: {"status": "processing", ...} — retry after 2-3 s. Poll no faster than once per 2 s (max 120 polls per task), and fetch the result promptly: the task is stored for only ~5 min before it expires with ERROR_NO_SUCH_CAPCHA_ID.

• when ready: {"status": "ready", "solution": {...}, "cost": ..., ...}

The solution object is CapMonster's raw solution, returned verbatim — its shape differs per captcha type. Extract fields by the shape documented for that type (get_docs), e.g. gRecaptchaResponse/token for reCAPTCHA/Turnstile, nested domains[host].cookies.* for DataDome/Imperva, data.randstr + data.ticket for TenDI, etc.

IMPORTANT: several types return a userAgent (or headers["User-Agent"]) inside the solution — the solved token is bound to it, so reuse that exact UA in the browser / subsequent requests when injecting (Cloudflare Challenge, FunCaptcha, AWS WAF, Binance, TenDI, Basilisk).

Poll a task to completion and return its solution (the usual way to collect a result after create_task).

Blocks, polling /getTaskResult every poll_interval_seconds until the task is ready or timeout_seconds elapses. This respects CapMonster's limits for you — the interval is clamped to a minimum of 2 s (the API rejects faster polling with ERROR_TOO_MUCH_REQUESTS) and the number of polls is capped at 120 per task.

Returns the same ready dict as get_task_result: {"status": "ready", "solution": {...}, "cost": ..., ...} The solution is CapMonster's raw solution, verbatim — its shape differs per captcha type (see get_task_result / get_docs).

IMPORTANT: several types return a userAgent (or headers["User-Agent"]) inside the solution — the token is bound to it, so reuse that exact UA when injecting (Cloudflare Challenge, FunCaptcha, AWS WAF, Binance, TenDI, Basilisk).

Raises an error on solve error (e.g. ERROR_RECAPTCHA_TIMEOUT — often a slow proxy) or if the task is still processing when timeout_seconds is reached (increase the timeout, or check the proxy/params and re-create the task).

Get CapMonster account balance.

List captcha task types supported by CapMonster, sourced from the OpenAPI spec.

Return the parameters for a CapMonster task type, from the live OpenAPI spec.

Use after get_supported_tasks() to look up what fields a task needs. Pass either a top-level type name (e.g. 'RecaptchaV2Task', 'TurnstileTask') or a CustomTask class name (e.g. 'DataDome', 'altcha', 'HUNT').

Returns:

• all_parameters: every field with its type/description (nested objects like metadata are expanded).

• required: the fields the spec marks required.

• description: the type's own spec note. READ IT — for several types it is where the spec records that the type has mutually-exclusive VARIANTS and which fields each needs (e.g. Turnstile's cloudflareTaskType, AWS WAF's challenge/captcha/cookie option-sets). The flat required list CANNOT express those variants, so it under-reports what a given variant needs.

• solution: the name of the solution schema this type returns.

⚠️ The flat field list is a starting point, not the whole contract. When description mentions variants/options/modes — or whenever you are unsure — confirm the exact per-variant field set and the solution shape against the worked examples via get_docs before building the task.

Fetch a CapMonster documentation page by its URL and return its text.

Use this to read a captcha type's docs (exact task parameters, how to extract them from a live page, and worked createTask/getTaskResult examples). Pick the URL from the llms.txt index (https://docs.capmonster.cloud/llms.txt) — it lists every doc page. Also accepts llms-full.txt and the OpenAPI spec URL.

Only URLs on docs.capmonster.cloud or api.capmonster.cloud are allowed.

Jumping to a section (preferred on big pages — avoids paging by hand):

• Pass section="<heading>" to return just that ##/### section (from its heading down to the next same-or-higher-level heading). Matching is case-insensitive and substring-based, so section="Examples of solving" or even section="examples" works. Great for going straight to "Create task", "Get task result", or "Examples of solving …".

• When a page is returned in chunks, the first chunk is prefixed with a section outline (each heading and the exact section="…" to jump to it), so you can pick the section you need in one follow-up call.

Paging (when you want the raw text, no section): Pages that don't fit in limit characters are returned one chunk at a time, starting at offset. The chunk is prefixed with a header showing the range, the total length, and (if there's more) the offset to pass on the next call — keep calling with that offset until the header says end of document.