Live view and sessions
Watch a hosted browser live, take control or share the view, manage your sessions, and keep a browser running so you can reconnect to it later.
Every request on this page can be sent from the page itself. Signed in, the examples carry your API key, and Send makes the real call and shows you the real answer, so you can change a field and see what it does.
A browser to try things on
Most of what follows needs a running browser. Start one here: it is an ordinary session, billed like any other (€1.00 per GB from your balance), and this one ends by itself after five minutes without a command, or fifteen in all.
POST Start a browser
The answer holds the session's id and a single-use connectUrl. A session starts when a client connects to that URL (until then it is pending, and it expires after 45 seconds). Press Connect and the docs connect, read the tab and disconnect, as your Playwright or Puppeteer script would; with keepAlive the browser keeps running for the requests below.
curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers' \ -H "authorization: Bearer cc_live_..." \ -H "content-type: application/json" \ -d '{"keepAlive":true,"url":"https://example.com","idleTimeoutSec":300,"timeoutSec":900,"note":"docs"}'
Live view: watch, take control, share
In the dashboard, click a session to see which sites its traffic went to and to watch it live. Press Take control to click, type, scroll, paste and navigate in it yourself, for example to sign in or get past a check your script cannot. Your script stays connected the whole time, so pause it while you act. Human input counts as activity, so a session you are driving is not closed as idle. Share makes a link anyone can open without an account, watch only or with control, for 15 minutes to 4 hours and never past the end of the session. A Watch + replay link shows the session live and, once it ends, its replay: every click, scroll and page drawn over the recording, for up to 14 days.
Through the API:
GET Open the live view
A live-view WebSocket for a running session (open it within 60 s). Binary messages are JPEG frames, text messages are {"url","title","tabs"}. With control=1 the answer says "interactive": true when control was granted. Watch it here opens the view on this page. Each timeline event also arrives as it happens, as {"ev": …} (see Recordings).
curl 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/live' \ -H "authorization: Bearer cc_live_..."
POST Share the live view
A link anyone can open without an account: control optional, 1 to 240 minutes (default 30), never past the end of the session. Treat a control link like your API key. With replay: true (and no control) it is a watch + replay link instead: live while the session runs, its replay after, 1 to 20160 minutes (default 10080, 7 days).
curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/share' \ -H "authorization: Bearer cc_live_..." \ -H "content-type: application/json" \ -d '{"control":false,"minutes":60}'
With control, send JSON text messages on the same WebSocket. Coordinates are fractions (0 to 1) of the frame you are looking at; anything else is ignored.
| Message | Does |
|---|---|
{"t":"mouse", | Press (down), release (up) or move; n is the click count, m the modifiers (Alt 1, Ctrl 2, Meta 4, Shift 8). |
{"t":"wheel", | Scroll by pixels at a point. |
{"t":"key", | A key going down or up, as a keyboard sends it. |
{"t":"text", | Insert text as if typed (up to 5000 characters). |
{"t":"nav",, forward, reload, or {"t":"nav", | History, reload, or open an http(s) address. |
GET /api/v1/browsers/<id> includes traffic: the top 20 sites by bytes for that session.
Managing sessions
GET One session
Its status, traffic, seconds and cost so far. The fields are described below the requests.
curl 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \ -H "authorization: Bearer cc_live_..."
GET Your sessions
Your balance and your sessions, newest first: 20 by default, up to 100 with limit. Filter by status and by note text; page back with before set to the createdAt of the last session you got. Press Use on a row to work with that session in the other requests.
curl 'https://www.clearcotelabs.com/api/v1/browsers' \ -H "authorization: Bearer cc_live_..."
PATCH Label a session
Set or change the note (at most 256 characters); null clears it.
curl -X PATCH 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \ -H "authorization: Bearer cc_live_..." \ -H "content-type: application/json" \ -d '{"note":"shop-de nightly"}'
DELETE Stop a session
A session nobody connected to ends at once; a running browser is closed by its server within one report interval, about 15 seconds.
curl -X DELETE 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \ -H "authorization: Bearer cc_live_..."
Give a session a note when you create it to find it again in the list and the dashboard. To start a session on the same server as an earlier one (warm caches, the same machine), pass that session's worker; when that server is full or offline, the session starts on another server and its warnings say so.
A session also ends when you close the browser or disconnect, and when a limit below is reached. A stop request ends a session nobody connected to at once; a running browser is closed by its server within one report interval, about 15 seconds. GET answers with:
{
"id": "bs_…",
"status": "active", // see the table below
"proxy": "managed", // or "custom"
"createdAt": "…", "startedAt": "…", "endedAt": null,
"endReason": null, // set once ended, e.g. "user", "balance", "launch_failed"
"stopRequested": false,
"usage": { "bytesUp": 120334, "bytesDown": 4812009, "gb": 0.0049, "seconds": 41 },
"traffic": [ { "site": "example.com", "bytesUp": 20400, "bytesDown": 3100000 }, … ], // top 20 sites
"costEur": 0.0050,
"pricing": { "eurPerGb": 1, "eurPerHour": 0 },
"queue": { "state": null, "position": null, "ahead": null, "etaSec": null, "updatedAt": "…" } // see below
}| status | Meaning |
|---|---|
pending | Created; nobody has connected yet. Counts towards the concurrency limit until it starts or expires (45 seconds after it was created; a run waits for its server instead). |
active | A browser is running and reporting usage. |
lost | No usage report for 5 minutes. Billed up to the last report; a late report puts it back to active. If none comes, it ends an hour after the longest a session may last (see Limits and errors): status ended, endReason worker_silent. If the server that ran it restarted, it ends as soon as that server is back: endReason worker_restarted, billed up to the last report. |
ended | Closed: you disconnected, stopped it, or a limit or the balance ended it. endReason says which. A launch its geo identity refused (geoIdentity strict) ends with endReason geo_refused:<code>, e.g. geo_refused:GEO_PROXY_COUNTRY_TIMEZONE_MISMATCH, and is not billed. |
expired | Nobody connected before expiresAt (45 seconds after creating it). Never billed. |
queue says where a starting browser stands in its server's launch queue, so a busy moment reads as a place in line rather than a slow connect. The create answer carries an estimate too: "queue": { "position": 3, "etaSec": 6 }, where the browser would join if you connected now (both null when the server reports no queue).
| queue field | Meaning |
|---|---|
state | waiting_for_client: created, nobody has connected yet. queued: you connected and the browser waits for a launch slot on its server. launching: it is starting now. null: running, ended, or the server reported no queue in the last 30 seconds. |
position | 1-based place in the server's waiting list while queued, else null. |
ahead | How many browsers start before this one: position - 1 while queued, 0 while launching, else null. |
etaSec | Estimated seconds until it starts while queued: the browsers ahead, launched as many at a time as the server allows, at its average launch time. Else null. |
updatedAt | When the server last reported its queue (ISO time), or null when it has not in the last 30 seconds. |
The list call, GET /api/v1/browsers, returns { balanceEur, sessions: [...] } with the same session objects, newest first.
Keeping a browser open and reconnecting
By default a session ends when your client disconnects. Start it with keepAlive: true and the browser keeps running instead, with its tabs, cookies and exit IP, so a later script (or the same one after a crash or a closed laptop) can pick up where the last one stopped:
POST Reconnect
A new single-use connect URL for a running keepAlive session (connect within 45 seconds). Connect picks the browser up again from this page, tabs and all.
curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/connect' \ -H "authorization: Bearer cc_live_..."
- Leave it running by disconnecting: Playwright's
browser.close()(overconnectOverCDPit only disconnects), Puppeteer'sbrowser.disconnect(), or simply ending your process. - End it with
DELETE /api/v1/browsers/<id>, or by sending the CDP commandBrowser.close: Puppeteer'sbrowser.close()does, and in Playwrightawait (await browser.newBrowserCDPSession()).send("Browser.close"). Until then it keeps its slot in your concurrency limit. - One client at a time: a reconnect while another client is attached is refused with
409, as is one for a session started withoutkeepAlive. - The limits still apply while nobody is connected:
idleTimeoutSec(raise it, up to 1800, for a browser you mean to come back to),timeoutSec,maxGband your balance. A page left open keeps loading its background traffic, which is billed like any other.