Skip to content

Options and identities

What you can set when you start a hosted browser: the options, the stealth defaults and identities, profiles that keep you signed in, a pinned release and the start page.

Options

All optional. Send them as the JSON body of the create call.

FieldTypeMeaning
identitystringOne label per account you run: the same device fingerprint AND the same residential IP, for as long as that IP stays online.
fingerprintstringDevice seed only (no IP pinning). The same seed gives the same device profile every time; with lightStealth on it picks from a small set of metadata profiles.
lightStealthbooleanDefault true: varies only the metadata axes the host can back up. Set false to turn it off.
platformwindowsAlways windows: the browsers run on Windows machines, and a persona of another system there reports GPU limits and fonts no such machine has. Another value starts a Windows session and warnings says so.
brandChrome | Edge | Opera | VivaldiBrowser brand the persona presents.
timezoneIANA namee.g. America/New_York. Omitted = the exit IP's. Given, it is kept as you wrote it and checked against the exit IP: under geoIdentity "strict" (the default) a time zone the exit's country does not use refuses the launch.
localestringAccept-Language, e.g. en-US,en. Omitted = a language of the exit IP's country. Given, it is kept and checked against the exit like timezone.
geoIdentity"strict" | "warn" | "auto" | "manual" | "off" | { mode?, acknowledge?, localePolicy? }Default "strict". Timezone, languages, Accept-Language, location and WebRTC address are resolved together from the exit IP, and checked against each other and against what you set, before the browser starts. strict: a contradiction refuses the launch: the connect answers 422 with the GEO_* code, and the session ends (not billed) with endReason geo_refused:<code>. warn and auto: the browser starts and the finding is reported. manual: your values as given, checked but never derived. off: the behaviour of geoip before geoIdentity. acknowledge: GEO_* codes you accept on purpose. localePolicy: "weighted" (the default: a fingerprint seed may draw any widely used language of the exit country) or "majority". The identity the browser presents is in the session.started event.
geoipbooleanOlder option, read only when geoIdentity is not set: true = geoIdentity "auto", false = "manual".
proxy"managed" | { server, username?, password? }Omitted = managed residential pool. Or your own proxy: http://, socks5:// or socks5h:// (rules below).
country2-letter codeManaged pool: exit country, e.g. us, de, gb.
stateregion codeManaged pool: exit state/region, e.g. ca, ny. Needs country.
citycity nameManaged pool: exit city, e.g. "los angeles". Needs state.
proxySessionstringManaged pool: sticky label. The same label returns the same exit IP later (kept for 24 hours).
timeoutSecnumberHard limit on the session length, in seconds (10 up to the account maximum below).
idleTimeoutSecnumberEnd the session after this long without a CDP command (10–1800).
maxGbnumberStop the session after this much traffic (0.001–1000).
headlessbooleanDefault true. With false the browser opens a real window on the server. Under the default lightStealth, the page then reports that server's own display (its whole screen, with the window maximized) instead of your identity's screen size; the identity still sets CPU cores, memory, colour depth and pixel ratio. Keep the default when the identity's screen should apply.
humanizebooleanDefault true. Your mouse moves along human paths: when a move or click lands far from the cursor, the server running the browser first walks there the way a hand would, pauses a moment before the press and holds each click for a human press time. A scroll of more than one wheel notch (100 px) arrives as whole notches at a human pace, and the page still scrolls exactly the distance you asked. Works for any client (Playwright, Puppeteer, raw CDP); drags, keys and touch are left as sent. false turns it off. See "Human input".
keepAlivebooleanDefault false. Keep the browser running when your client disconnects, until you end it (DELETE, or the CDP command Browser.close) or a limit does; reconnect with POST /api/v1/browsers/<id>/connect.
versionstringRun a specific Clearcote release, e.g. "152.0.7977.82-r21" or "r21". Omitted = the current release. See "Pinning a release".
profile"name" | { name, persist? }Load a saved profile (cookies + site storage). With persist: true, save it back when the session ends. See "Profiles".
urlhttp(s) URLOpened in the first tab before you connect: you find it already loading.
adblockbooleanRefuse known ad and tracker hosts before they load, so they are never billed. Default false.
solveSlidersbooleanDefault true. Slide-to-verify challenges are dragged for you, in any tab or frame; false leaves them to your script. See "Slider challenges".
solveCheckboxesbooleanDefault true. "Verify you are human" checkboxes are clicked for you, in any tab or frame; false leaves them to your script. See "Checkbox challenges".
solvePressHoldbooleanDefault true. "Press and hold" verification buttons are held for you until they report done, in any tab or frame; false leaves them to your script. See "Press-and-hold challenges".
challengeServicetrue | { categories?, sites?, key?, apiKey?, mode?, maxSolves?, maxSpendEur? }Default off. Challenges the free actions cannot clear go to a solving service, with your own key or ours (billed per solve). true (or no categories) auto-selects: every challenge it recognises, in token, clearance, block-page and image; or list categories and sites yourself. See "Challenge service".
recordbooleanDefault false. Record the session as an MP4; GET /api/v1/browsers/<id>/recording once it is ready (kept 14 days).
notestringYour label for the session (at most 256 characters). Shown in the dashboard; filter by it in the list.
workerstringPlace the session on the same server as an earlier one (its worker). If that server is full or offline, it starts on another one and warnings says so.

Stealth defaults and identities

Every session starts from the settings on the recommended settings page: a Windows persona (the browsers run on Windows machines, so that is the system they can back up), lightStealth on, a seed, timezone and language that follow the exit IP with your own proxy or ours, the Widevine module a Google Chrome has (so requestMediaKeySystemAccess("com.widevine.alpha") succeeds), and human mouse movement (below). With lightStealth (the default) the seed picks the device profile from a small set that varies CPU cores, memory and pixel ratio; canvas, WebGL and audio are rendered by the machine the session runs on. The graphics card a session reports to WebGL is drawn for each session from a range of real models of the same class as that machine's, and the same identity reports the same card, so sessions on one machine report different cards while the WebGL limits and video codec answers stay consistent with them. Set lightStealth: false for a full per-seed persona: canvas and WebGL readbacks get per-site noise from the seed, and the GPU strings, screen and audio settings (sample rate, latency) follow the persona. Without an identity or fingerprint, each session gets a random seed and a new IP.

Pass identity: "account-42" to come back with the same device profile, on the same IP for as long as that residential IP stays online, in later sessions, which is what a logged-in account expects. Identities are private to your account: another customer using the same label gets their own seed and IP. On its own an identity does not keep cookies: for that, use a profile.

Human input

Stock Playwright and Puppeteer move the mouse in one jump: a single move lands on the target and the click follows within a millisecond or two. A hosted browser smooths that out on the server, next to the browser, for any client: when a move or a click lands far from where the cursor is, the server first walks there the way a hand would (curved, with the speed and small corrections of a real reach), then delivers your event. A press waits a moment after the pointer arrives, the way a hand settles, and each click is held for a human press time before it is released. One identity keeps one way of moving. Your script needs no change, and it gets slower by about a second per click.

Scrolling gets the same treatment. A scroll of more than one wheel notch (100 px on the Windows machines the browsers run on) arrives as whole notches in short bursts, the way a finger turns a wheel, after the pointer has moved to the scroll point if it was elsewhere. The page scrolls exactly the distance you asked, the last notch carrying the remainder, and your call returns when that notch is out.

Left exactly as you send them: moves of a few pixels (a client that already moves in small steps, like the SDK's own humanize), drags with a button held, a scroll of one notch or less, touch and the keyboard. Pass humanize: false when you need the raw speed.

Profiles: sign in once

A profile keeps a session's cookies, localStorage and IndexedDB under a name, so the next session on that name starts signed in. Pass profile: { name: "shop-account", persist: true } to load it and save it back when the session ends, or just profile: "shop-account" to load it read-only. The first session on a new name starts empty and creates it.

javascript
// Every run: the same body. The first one starts signed out; sign in, then close the browser
// and the session saves the cookies and site storage. Every later run starts signed in.
const res = await fetch("https://www.clearcotelabs.com/api/v1/browsers", {
  method: "POST",
  headers: { authorization: "Bearer cc_live_...", "content-type": "application/json" },
  body: JSON.stringify({ profile: { name: "shop-account", persist: true }, country: "de" }),
});
  • Same device, same IP. A profile brings its own identity (profile:<name>), so the site sees the same fingerprint, and the same residential IP while that IP stays online, like a returning customer. Pass identity or fingerprint yourself to choose otherwise, and keep the country the same between runs.
  • One writer at a time. Only one running session may save to a profile; a second one with persist: true gets 409 PROFILE_IN_USE. Read-only sessions can run alongside it and see the last saved state.
  • Saved when the session ends, whether you close the browser, disconnect, stop it or a limit ends it. If the browser crashed, the previous saved state is kept rather than replaced by a partial one. Session cookies (those without an expiry) are dropped, as a real browser drops them on restart.
  • Up to about 3.5 MB compressed. If a site's IndexedDB makes it larger, IndexedDB is left out; cookies and localStorage are still saved.
  • Private. A profile is yours alone (another customer's “shop-account” is a different profile), stored encrypted, and only handed to the server running your session. List them with GET /api/v1/browsers/profiles, delete one with DELETE /api/v1/browsers/profiles/<name>, or use the dashboard.

Already signed in somewhere else? Cookie sync copies those cookies into a profile, so the first session starts signed in too.

Pinning a release

Sessions run the current Clearcote release. To run an older one, pass version: the full release ("156.0.8078.47-r51"), just the rebuild ("r51"), a Chromium version or major ("155" picks the newest build of it), or "latest". These are the same releases the SDK's version option downloads, so a hosted session and a local run on the same pin use the same build.

javascript
const res = await fetch("https://www.clearcotelabs.com/api/v1/browsers", {
  method: "POST",
  headers: { authorization: "Bearer cc_live_...", "content-type": "application/json" },
  body: JSON.stringify({ identity: "account-1", version: "156.0.8078.47-r51" }),
});
const { connectUrl, engine, warnings } = await res.json();
// engine   -> { version: "156.0.8078.47", revision: "r51", pinned: true }
// warnings -> [ "This session runs 156.0.8078.47-r51, older than the current ... " ]
  • Check warnings. An older release does not have what later releases added. Options and fixes that came after it may be missing, or silently ignored instead of rejected, so a setting that works on the current release can quietly do nothing on a pinned one.
  • The response's engine always says which release the session runs, pinned or not.
  • A release that does not exist is a 400 with code UNKNOWN_VERSION, and the message lists the releases you can pick.
  • The first session on a release our servers have not used yet can take up to a minute longer to start while the build is fetched. Later sessions on it start as fast as any other.

Start page and ad blocking

  • url opens a page in the first tab before you connect, so it is already loading when your script attaches.
  • adblock: true refuses requests to well-known ad, ad-verification and analytics hosts before they are made, so they are never billed. The list is deliberately conservative (tag managers, consent tools, login SDKs and CAPTCHAs are left alone), but a few sites notice missing ads; leave it off where that matters.