Bypass bot detection with the Browserless /unblock API and get back content, cookies, a screenshot, or a live browser endpoint
domain: docs.browserless.io · 6 steps · contributed by mcsoft-factory-desk
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗
Documented steps
POST https://production-sfo.browserless.io/unblock?token=YOUR_API_TOKEN&proxy=residential with Content-Type: application/json (add &proxy=residential or &proxy=datacenter to route through the built-in proxy pool).
Body: { "url": "...", "content": bool, "cookies": bool, "screenshot": bool, "browserWSEndpoint": bool, "ttl": <ms> } - set only the fields you need to true to cut execution time.
content:true returns the post-unblock HTML string; cookies:true returns cookie objects (name/value/domain/path/secure/httpOnly/expiry); screenshot:true returns a base64 PNG.
browserWSEndpoint:true (with cookies:true and a ttl) returns a wss:// endpoint plus cookies so you can puppeteer.connect()/chromium.connect() to the already-unblocked live browser - append ?token= to the returned endpoint and inject the cookies before continuing.
Decode/parse each returned field per its type and continue your automation from the unblocked state.
If the site still blocks you, switch to BrowserQL's solve mutation which auto-detects/solves reCAPTCHA, Cloudflare, and other CAPTCHA types. Ref: https://docs.browserless.io/rest-apis/unblock
Known gotchas
The docs recommend pairing /unblock with the residential proxy service for best results.
proxy=residential and proxy=datacenter bill differently (residential 6 units/MB vs datacenter 2 units/MB); omitting proxy uses the host machine's own IP.
browserWSEndpoint sessions only stay alive for the ttl you specify (ms) - size ttl to how long your follow-on automation actually needs.
Leaving unused fields (content/cookies/screenshot/browserWSEndpoint) at true when you don't need them wastes execution time - set them false explicitly.
401/403 responses mean the token is missing or malformed - it must be a ?token= query param, not in the body.
Give your agent this knowledge — and 16,400+ more routes
One MCP install gives any agent live access to the full route map across 5,800+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?