Guide

CAPTCHA solving

Sessions created with solve_captchas watch every page for a challenge, solve it through a solver provider, and inject the token — your agent just keeps going. Included on paid plans.

Enable it

POST /sessions

{ "solve_captchas": true, "proxies": true }   // proxies recommended: solves are bound to the session's IP

Detection runs inside the session (an isolated-world observer plus network sniffing) for reCAPTCHA v2, v3 (with action and minimum score), reCAPTCHA Enterprise, hCaptcha, and Cloudflare Turnstile. One solve is in flight per session at a time, and the same sitekey + URL is not re-solved within five minutes. On the Free plan the flag is refused with 403 captcha_not_on_plan.

Know when it happens

Two signals, so existing Browserbase/Stagehand-style code works unchanged and event-driven code has something structured to read:

Channel	Events
Page console	`browserview-solving-started` and `browserview-solving-finished` are logged with `console.log` in the page — listen with `page.on("console")`.
Session event stream	`captcha.detected`, `captcha.solving`, `captcha.solved`, `captcha.failed` — each `{ type: "captcha.*", captcha_type, sitekey, url, ms?, error? }` — in the replay JSONL and the live event stream.

wait for a solve (Playwright / Patchright)

await Promise.race([  page.waitForEvent("console", (m) => m.text() === "browserview-solving-finished"),  page.waitForTimeout(30_000),]);

Solver status

GET /sessions/{id}/captcha

{  "enabled": true,  "status": "solved",          // idle | detected | solving | solved | failed  "type": "recaptcha_v2",  "last_error": null,  "solves": 1,  "updated_at": "2026-08-29T20:14:02Z"}

Solves are also totalled on the session object as usage.captcha_solves and shown per session in the console's History.

Manual solve

Found a sitekey yourself? The explicit endpoint is still there and returns a token for you to inject:

POST /sessions/{id}/captcha/solve

{  "type": "recaptcha_v2",    // recaptcha_v2 | recaptcha_v3 | recaptcha_enterprise | hcaptcha | turnstile  "sitekey": "6Le...",  "url": "https://example.com/login",  "action": "login"          // recaptcha_v3 only} // 200 → { "token": "<solution>", "type": "recaptcha_v2" }// 502 → the provider could not solve it

Tokens are short-lived (v3: two minutes, Turnstile: five and single-use) — inject right away.
Enterprise reCAPTCHA scores server-side on IP and session, so a managed proxy that stays sticky for the session materially improves pass rates.
When a solve fails, hand off to a human: the control-scope viewer is built for exactly that.