Recordings and the event timeline
Two ways to see what a hosted browser did after the fact. A recording is a video of the browser's screen. The event timeline is a list of what happened, with timestamps: pages, tabs, clicks, scrolls and typing, what the challenge solvers decided, agent steps, hand-offs and limits. The replay puts the two together: the video with every action drawn over it. All of it works for sessions you drive and for agent runs.
Record a session
Pass record: true when you create the session or the run. Recording is off by default.
curl -X POST https://www.clearcotelabs.com/api/v1/browsers \
-H "authorization: Bearer cc_live_..." -H "content-type: application/json" \
-d '{"record": true, "country": "de"}'
# an agent run: the same field
curl -X POST https://www.clearcotelabs.com/api/v1/runs \
-H "authorization: Bearer cc_live_..." -H "content-type: application/json" \
-d '{"task": "Open the pricing page and read the cheapest plan", "url": "https://example.com", "record": true}'- The video shows the active tab, as the live view does, at a few frames per second, in an H.264 MP4 of 1280×800 (other window sizes are letterboxed). It is meant for seeing what happened, not for smooth playback.
- Recording stops when the session ends, or when the file reaches a size cap; the session itself carries on.
- It is not billed as traffic: the frames are captured on our server, not downloaded from the internet.
- Only some servers can record. A session with
record: trueis only started on one that can; if none is free you get the usual503.
Status
The session view (GET /api/v1/browsers/<id>, and the session of a run) has a recording field: null when the session was not recorded, otherwise:
"recording": {
"status": "ready", // recording | processing | ready | failed | expired
"bytes": 18230411,
"durationSec": 312.4,
"expiresAt": "2026-10-16T09:20:11.000Z" // when it stops being available
}bytes, durationSec and expiresAt are null until the recording is ready.
| status | Meaning |
|---|---|
recording | The session is running and being recorded. |
processing | The session has ended; the file is being finished and uploaded. |
ready | Download or share it. |
failed | The recording could not be made or uploaded: the session never started, the server could not finish the file, or it had still not arrived 25 hours after the session ended. There is no file. |
expired | Past its retention period: the file is deleted. |
The file is uploaded once the session has ended, so a recording turns ready a little after the session does; a long one takes longer. If it has still not arrived 25 hours after the session ended, it is marked failed. To be told instead of polling, add a recording.ready webhook.
Download
GET /api/v1/browsers/<id>/recording answers with a 302 redirect to a private download link that works for at most 5 minutes. Follow it right away rather than storing it. While the recording is recording or processing the answer is 409 with code NOT_READY; a session that was not recorded, whose recording failed, or whose recording has expired is a 404 (NOT_FOUND).
# -L follows the redirect to the file
curl -L -o session.mp4 -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/<id>/recording
# or with the SDK's command
clearcote cloud recording <id> -o session.mp4from clearcote.cloud import Cloud
cloud = Cloud()
cloud.browsers.download_recording("bs_…", "session.mp4") # saves the file
url = cloud.browsers.recording_url("bs_…") # or just the short-lived linkThe dashboard plays the recording next to the session's details, as a replay.
The replay
A replay plays the recording with the session's timeline drawn over it: the pointer and its path, a ring where each click landed, the way of each drag (a slider the solver dragged included), each scroll and burst of typing, the page that opened, what the challenge solvers decided and the agent's steps as captions. Beside it, the activity list: click a row to jump there, and the row of the moment follows the video. Speed it up, or skip the stretches where nothing happens. A session that was not recorded can be replayed too: its actions then play on a plain stage, in order and at their real pace.
Under the picture, the session's figures, at the moment you are watching and in all: how long it has run, how much went through its proxy (down and up), the pages it opened, the clicks, scrolls and characters typed, and how its challenges went. A throughput chart shows the traffic on the same clock as the video, with the playhead on it; click the chart to jump there. Beside it, the sites that took the most data, and below, how the session reached the internet (residential, your own proxy or direct, with the country it asked for), the connections it opened and how many failed, the proxy's retries and the ads and trackers adblock refused. A shared link never shows the proxy's address or what the session cost; your dashboard adds the cost.
Typed text is never recorded in the timeline, only how many characters were typed and the names of keys such as Enter or Tab; the video shows what the page showed, as below.
Share a session: live, then its replay
A watch link shows the session live while it runs, with what it does listed beside it, and once it ends the same link opens its replay. No account is needed to open it, and it never allows control:
curl -X POST -H "authorization: Bearer cc_live_..." -H "content-type: application/json" \
-d '{"replay": true}' https://www.clearcotelabs.com/api/v1/browsers/<id>/share
# { "url": "https://www.clearcotelabs.com/live/bs_…#t=…", "expiresAt": "…", "control": false, "replay": true }replay: true works for any of your sessions, running or finished. minutes sets how long the link works: 1 to 20160 (14 days), default 10080 (7 days). control does not apply (400). The replay plays the recording when the session was recorded (record: true), and the actions on a plain stage when it was not. The token is after the #, so it never reaches a server log, and it stays in the page's address, so the address can be passed on as it is. Anyone holding the link can watch the session and its replay until it expires, so share it only with people who may see it. The timeline it shows gives page addresses without their query string. In the dashboard, the live view's Share makes the same link (Watch + replay), and a finished session has Share replay.
Share a recording
To show only the video to someone without an account, make a recording link. It opens a page on this site that replays it, until the link expires:
curl -X POST -H "authorization: Bearer cc_live_..." -H "content-type: application/json" \
-d '{"recording": true, "minutes": 120}' https://www.clearcotelabs.com/api/v1/browsers/<id>/share
# { "url": "https://www.clearcotelabs.com/replay/bs_…#t=…", "expiresAt": "…" }It is the same share call as for a live-view link, with recording: true; minutes sets how long the link works: 1 to 240, default 30, and never past the recording's expiresAt. A recording that is not ready yet answers 409 NOT_READY, and control does not apply (400). The token is after the #, so it never reaches a server log; pass the link on whole. The kinds of link are kept apart: a recording link cannot open a live view, and a live-view link cannot open a replay (a watch link opens both). Anyone holding a recording link can watch the video, so treat it like the recording itself.
Retention and privacy
- Recordings are stored privately for 14 days from when they turn
ready. Atrecording.expiresAtthe download and replay links stop working and the file is deleted soon after; download what you want to keep before then. - Download links are only given to you (your API key or the dashboard) and stop working after at most 5 minutes; until then, anyone holding one can use it.
- A recording shows what the page showed. Anything typed into an ordinary field is on the video, including a secret typed into a field that displays its text. Password fields show dots, as on screen. Leave recording off for runs whose screens you do not want stored.
The event timeline
Every session keeps a timeline. Read it with GET /api/v1/browsers/<id>/events, which works for runs too (a run's id is its session id):
curl -H "authorization: Bearer cc_live_..." "https://www.clearcotelabs.com/api/v1/browsers/<id>/events?after=0&limit=200"{
"events": [
{ "seq": 1, "at": "2026-10-02T09:14:05.410Z", "type": "session.started", "data": { "kind": "run" } },
{ "seq": 2, "at": "2026-10-02T09:14:05.912Z", "type": "run.started", "data": { "jet": { "version": "0.1.0", "commit": "cd7011c…" } } },
{ "seq": 3, "at": "2026-10-02T09:14:06.730Z", "type": "navigation", "data": { "url": "https://www.gov.uk/", "title": "Welcome to GOV.UK" } },
{ "seq": 4, "at": "2026-10-02T09:14:07.950Z", "type": "run.step",
"data": { "step": 1, "kind": "click", "action": "Reject additional cookies", "text": null, "probability": 0.85, "url": "https://www.gov.uk/" } },
…
{ "seq": 19, "at": "2026-10-02T09:14:21.006Z", "type": "session.ended", "data": { "reason": "run_finished" } }
],
"next": null
}seqnumbers a session's events in order, from 1; there can be gaps.atis when it happened.afterreturns the events after thatseq(default 0, the start);limitis 1 to 500, default 200. Values outside those ranges are a400.nextis theafterfor the following page, ornullwhen you have everything stored so far.- While a session runs, its events arrive in batches with the browser's usage reports, about every 15 seconds. To follow a live session, keep asking with
afterset to the lastseqyou saw. - A session keeps at most 1000 events, and besides them up to 2000
inputand 1500trafficevents; onetruncatedevent marks where events were dropped. Events are deleted 2 days after the session ends. - An
inputevent is sent once the action is over, so itsat(when the action began) can be earlier than the event before it. Sort byatto show the order things happened in. - A live view gets the events as they happen, without waiting for a usage report: each one arrives on its WebSocket as a text message
{"ev": {"seq", "at", "type", "data"}}, withatin milliseconds (the kinds a shared view may show: noclient.connected, refused commands or hosts, profile details, or costs).
from clearcote.cloud import Cloud
cloud = Cloud()
after = 0
while True:
page = cloud.browsers.events("bs_…", after=after)
for e in page["events"]:
print(e["seq"], e["at"], e["type"], e["data"])
if page["next"] is None:
break
after = page["next"]Event types
| type | data | Meaning |
|---|---|---|
session.started | { kind, proxy, country?, state?, city?, adblock, headless, geo? } | The browser is up. kind is "cdp" for a session you drive, "run" for an agent run. |
navigation | { url, title } | A tab moved to a new address. At most one per second per tab. |
tab.opened | { url } | A new tab or pop-up opened. |
tab.closed | {} | A tab closed. |
cdp.denied | { method, reason } | The hosted browser refused a CDP command, for example a file upload from the server. At most 50 per session. |
profile.loaded | { cookies, files } | A saved profile was loaded into the browser. |
profile.saved | { cookies, bytes } | The profile was saved back at the end of the session. |
run.started | { jet: { version, commit } } | Jet started on a run, and which version it is. |
run.step | { step, kind, action, text, probability, url } | One step of a run, as in result.steps. Secrets in text show as {{name}}. |
run.finished | { status, detail } | Jet stopped, with the result's status (done, blocked, needs_input, budget, error). |
handoff.requested | { reason } | A run's agent asked for a person (handoff: true). A hand-off you start with POST …/handoff is not in the timeline; use the handoff.requested webhook for those. |
handoff.done | {} | A run's hand-off was marked done (the "I'm done" button, the dashboard or the API) and the agent carried on. |
recording.started | { fps } | The recording's first frame: the video's 0 s. An event's place in the video is its at minus this one's. fps is the frame rate. |
slider | { variant, outcome, attempt?, reason?, site } | An attempt at a slider challenge (solveSliders). variant is slide or puzzle; outcome is passed (the challenge went away), failed (it was still there, attempt counts them, at most three per page) or skipped, with a reason, when a puzzle was left alone rather than dragged to a guess. |
checkbox | { outcome, attempt?, reason?, site } | An attempt at a checkbox challenge (solveCheckboxes): a "verify you are human" box was clicked. outcome is passed (the box went away or was ticked), failed (it was still waiting, attempt counts them, at most three per page) or skipped, with a reason. |
pressHold | { outcome, attempt?, reason?, site } | An attempt at a press-and-hold challenge (solvePressHold): a press-and-hold verification button was held until it reported done. outcome is passed (the button reported done or went away), failed (it did not; a hold that ran out of time has the reason timeout, and attempt counts the tries) or skipped, with a reason. |
challenge.detected | { category, solvable, reason?, site } once per challenge per page, with challengeService on | With challengeService on: a challenge the page showed, once per challenge per page. category (token, score, clearance, block-page, image), solvable, and a reason when it is not (not_supported, needs_relay, category_off, ip_blocked, missing_parameters). |
challenge.service | { category, outcome, reason?, applied?, attempt?, ms?, costUsd?, site } one per answer the solving service was asked for | One ask to the solving service (challengeService). outcome is solved (the answer went in and the challenge went away; applied says how: callback, field, cookie, typed, dragged, hook), failed or skipped, with a reason (unsolved, still_there, bad_key, no_balance, budget, ...). costUsd is what the service charged for it. |
client.connected | { ip, ua } | A CDP client connected to the session (also on a reconnect): the address the session's server saw and the client's User-Agent. |
egress.refused | { host, port, reason } | The browser tried to reach a private, loopback or link-local address (reason: private, loopback, link-local, own-ip, blocked-range) or a blocked port such as 25 (blocked-port), and the connection was refused. Once per host and port, at most 50 per session. |
input | { kind, by, x?, y?, vw?, vh?, shown?, ms, path?, x2?, y2?, dx?, dy?, button?, n?, chars?, keys? } | One action on the page, once it is over: kind is click, drag, tap, scroll, type, move (the pointer moved and stopped without a click) or capped (the session's actions stop being kept here). by says who acted: client (your connection), agent (a run's agent), viewer (a person in the live view) or solver (the challenge solvers). x, y are CSS pixels in the page's viewport vw × vh; shown is true on the tab the live view and the recording show, false on another tab. path is the pointer's way as [ms from at, x, y], ms how long the action took. type gives chars, how many characters were typed, and keys, the names of keys such as Enter or Tab and shortcuts such as Ctrl+V; never the text. |
traffic | { up, down, conns, failed, retries, blocked } | What went through the session's proxy so far, cumulative: up and down in bytes, conns connections opened, failed connections that could not be made, retries tunnels tried again after a hiccup of the proxy, blocked requests refused by adblock. Every few seconds while any of them changes; the replay charts it. |
limit | { reason } | A limit was reached: max_duration, idle_timeout, max_bytes, max_files_size (the session's file folder is full), or max_recording_size (only the recording stopped; the session carries on). Running out of balance shows only in session.ended. |
geo.drift | { code: "GEO_EXIT_ROTATING" } your own proxy's exit IP changed after the start: the timezone, language and WebRTC address describe the previous one | |
session.ended | { reason, code? } | The session ended, and why (the same as the session's endReason). |
truncated | {} One marker at the first event that was not kept: the session reached 1000 stored events | Events were dropped from here on: the session passed 1000 events (input and traffic events have their own allowances), or its server could not send them in time. At most one per session. |
Event data is kept small: an event whose data is over 2 KB stores { "truncated": true } instead. Secrets never appear in events; where a step typed one, its text shows {{name}}. New event types may be added, so skip types you do not know rather than failing on them.