Challenges

Hosted browsers handle slider and checkbox challenges by themselves. The challenge service, off unless you turn it on, takes the ones they can't.

Slider challenges

Some sites answer with a slide-to-verify challenge: a handle to drag to the end of a bar, or a puzzle piece to drag into its gap. A hosted browser handles these for you, in any tab and inside frames. It is on by default; pass solveSliders: false when your script deals with them itself.

• What it does. A plain slider is dragged to the end. A puzzle is dragged until the piece sits in its gap: the browser finds the gap in the puzzle image, then checks where the piece actually went and corrects. The drag is a pressed, human-paced mouse movement, not a jump.
• When it holds back. If it cannot find the gap with confidence, it leaves the puzzle alone rather than guess, because a wrong drag can count against the session. It tries at most three times per page, and it waits while someone controls the session from the live view or during a hand-off.
• What you see. Every attempt is a slider event in the session's event timeline, with whether the challenge went away afterwards (passed) or not (failed), or why a puzzle was left alone (skipped).
• Only challenges are touched: a slider counts as one when the page or the widget around it says so (a captcha or verification check). Range inputs, carousels and price filters are left alone. Your script's own mouse input and a drag in progress can interleave, so pause clicks while a challenge is on screen, or turn the option off.

Checkbox challenges

Some sites ask you to tick a “verify you are human” box first. A hosted browser clicks it for you, in any tab and inside frames, including widgets that hide the box from page scripts. This is a separate option from sliders, also on by default; pass solveCheckboxes: false to handle these boxes yourself.

• Which boxes. Only a checkbox whose own wording says it is a human check (human, robot, captcha, verify you are…). A “remember me” or “I agree to the terms” box is never clicked, whatever else the page says.
• The click. A human-paced pointer movement to the box, a short pause, and a press held as long as a person's click. If the box opens a slider next, the slider is handled as a slider.
• What you see. Every attempt is a checkbox event in the session's event timeline: passed when the box went away or was ticked, failed when it was still waiting. At most three attempts per page, and none while someone controls the session from the live view or during a hand-off.

Challenge service

For sites that keep challenging after the free slider and checkbox actions, a hosted browser can hand the harder challenges to a solving service. It is off unless you ask for it: pass challengeService: true to let it pick by itself, or an object to choose what it may do. It uses your own solving-service key, or ours (billed per solved challenge).

Choosing which challenges it handles

You never tell it which widget or which vendor a site uses. The hosted browser recognises each challenge on the page by itself, from its markup, its frames and how it behaves, and sorts it into one of five categories. You choose categories, not widgets.

• Auto-select. challengeService: true, or an object without categories (or with categories: "auto"): every challenge it recognises in token, clearance, block-page and image is handled, on every site. score is left out because the browser already earns its own score token: answering it from elsewhere costs a solve on every call, so it is only worth it for a site that rejects your sessions' scores.
• Pick categories. categories: ["token", "image"] handles only those. A challenge of another category is still reported in the timeline (as category_off), never paid for.
• Pick sites. sites: ["shop.example"] limits it to those hosts and their subdomains; elsewhere nothing is reported or asked. Combine it with categories for “this kind of challenge on that site”.
• Not sure what a site uses? Run it once with mode: "report": nothing is asked or paid for, and the timeline lists every challenge the pages showed as challenge.detected with its category and whether it can be solved. Then turn on exactly those categories for that site.

// In the body of POST /api/v1/browsers, or in the SDK's launch options (cloud: true)

// Auto-select: every challenge it recognises (all categories but score), on every site
challengeService: true

// Only widgets that hand out a token, only on one site, at most EUR 0.20 per session
challengeService: { categories: ["token"], sites: ["shop.example"], maxSpendEur: 0.2 }

// Only full-page waits and block pages, with your own solving-service key
challengeService: { categories: ["clearance", "block-page"], key: "own" }

// Auto-select plus the score check, on one site
challengeService: { categories: ["token", "clearance", "block-page", "image", "score"], sites: ["shop.example"] }

// First find out what a site uses: report only, nothing asked or paid for
challengeService: { mode: "report" }

All fields

How it works

• Free first. The slider and checkbox actions always go first. The service is asked only when a challenge is still there after its fair chance: a picture puzzle came up, an invisible widget opened its puzzle, a widget stayed unanswered for about 15 to 25 seconds, a full-page wait did not clear in about 20 seconds, or the page is a block page or a text code.
• How the answer goes in. The way the page expects it: a token into the widget's response field and its callback, a cookie for the site and a reload, a code typed into its box, a jigsaw dragged into place. Then it checks that the challenge is gone, like the free actions.
• The same IP. Full-page waits and block pages must be solved from the IP that uses the answer: the service solves them through your session's own exit IP, over a short-lived, single-use connection. A token a site rejects is asked for once more the same way.
• Your key or ours. key: "own" uses your solving-service key: store it once in the dashboard (Settings), or pass apiKey with the request. It is stored encrypted, never shown again and never reaches the browser; you pay the service directly. key: "managed" uses ours: each solved challenge is billed from your hosted balance at the service's own price × 1.5, failed attempts free. Leave key out to use your stored key if you have one, ours otherwise.
• Limits. At most 2 asks per challenge per page. Per session, maxSolves (default 10, at most 100) and maxSpendEur (default €0.50): the asking stops at either. On our key, a monthly cap per account (set it in the dashboard, at most €25). A wrong key or an empty balance at the service stops the asking for that session.
• What you see. challenge.detected once per challenge per page, and challenge.service for every ask (solved, failed or skipped, with the reason and the service's cost) in the event timeline; challenges (whose key, how many asks, what our key's solves cost) on the session. In an agent run, the agent waits while the service works on a page.
• Some widgets are seen but not solved: their answer cannot be put back into a page in a general way. They are reported with solvable: false and never paid for. The page address and the challenge's details go to the solving service.

What happens with each kind

The free actions still come first: a plain slider is dragged, a jigsaw whose gap the browser can find is placed, and a box that ticks on a click is clicked, all without asking the service. In the widget, the box itself can stay unticked after a token went in: the page reads the response field and the callback, not the box.

From the SDKs

SDK 0.38.0 or newer takes the option on a cloud launch (Python: challenge_service, which also accepts max_solves, max_spend_eur and api_key). The timeline says what happened; its last events arrive a few seconds after the session ends.

import { Cloud, launch } from "clearcote";

const browser = await launch({
  cloud: true,
  challengeService: { categories: ["token", "image"], sites: ["shop.example"], maxSpendEur: 0.2 },
});
const page = await browser.newPage();
await page.goto("https://shop.example/signup");
// ... your script: challenges the free actions cannot clear are answered for you
const id = browser.cloudSession.id;
await browser.close();

const { events } = await new Cloud().browsers.events(id);
for (const e of events) if (e.type.startsWith("challenge.")) console.log(e.type, e.data);
// challenge.detected { category: "token", solvable: true }
// challenge.service  { category: "token", outcome: "solved", applied: "callback", attempt: 1, ms: 12725, costUsd: 0.00013 }

from clearcote import Cloud, launch

browser = launch(cloud=True, challenge_service={"categories": ["token", "image"], "sites": ["shop.example"], "max_spend_eur": 0.2})
page = browser.new_page()
page.goto("https://shop.example/signup")
session_id = browser.cloud_session["id"]
browser.close()

for e in Cloud().browsers.events(session_id)["events"]:
    if e["type"].startswith("challenge."):
        print(e["type"], e["data"])