录像与事件时间线
事后查看托管浏览器做了什么,有两种方式。录像是浏览器屏幕的视频。事件时间线是带时间戳的事件列表:页面、标签页、点击、滚动和输入、验证求解器的判断、智能体的步骤、人工交接以及触发的上限。回放把两者结合起来:在视频上叠加显示每一个操作。以上功能既适用于你自己驱动的会话,也适用于智能体任务。
录制会话
创建会话或任务时传入 record: true。录制默认关闭。
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}'- 视频与实时画面一样显示当前活动的标签页,每秒几帧,格式为 1280×800 的 H.264 MP4(其他窗口尺寸会加黑边)。它用于查看发生了什么,并不追求流畅播放。
- 会话结束或文件达到大小上限时,录制停止;会话本身会继续运行。
- 录像不按流量计费:画面是在我们的服务器上捕获的,而不是从互联网下载的。
- 只有部分服务器支持录制。带
record: true的会话只会在支持录制的服务器上启动;如果没有空闲的服务器,你会收到通常的503。
状态
会话视图(GET /api/v1/browsers/<id>,以及任务的 session)中有一个 recording 字段:会话未录制时为 null,否则为:
"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
}在录像变为 ready 之前,bytes、durationSec 和 expiresAt 均为 null。
| status | 含义 |
|---|---|
recording | 会话正在运行,并且正在录制。 |
processing | 会话已结束,文件正在收尾并上传。 |
ready | 可以下载或分享。 |
failed | 录像未能生成或上传:会话从未启动、服务器无法完成文件,或者会话结束 25 小时后文件仍未到达。没有文件。 |
expired | 已超过保留期限,文件已删除。 |
文件在会话结束后才上传,所以录像会比会话稍晚一些变为 ready;录像越长,耗时越久。如果会话结束 25 小时后仍未到达,就会被标记为 failed。如果想收到通知而不是轮询,可以添加一个 recording.ready webhook。
下载
GET /api/v1/browsers/<id>/recording 会返回一个 302 重定向,指向一个最多 5 分钟内有效的私有下载链接。请立即跟随该链接,而不要保存它。录像处于 recording 或 processing 状态时,返回 409,错误码为 NOT_READY;会话未录制、录像失败或录像已过期时,返回 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 link仪表盘会在会话详情旁边以回放的形式播放录像。
回放
回放会在播放录像的同时叠加显示会话的时间线:指针及其移动轨迹、每次点击落点处的圆环、每次拖动的轨迹(包括求解器拖动的滑块)、每次滚动和每段连续输入、打开的页面、验证求解器的判断,以及以字幕形式显示的智能体步骤。旁边是活动列表:点击某一行即可跳转到该处,当前时刻所在的行会随视频移动。你可以加速播放,或跳过没有任何动静的片段。未录制的会话同样可以回放:此时它的操作会在一个空白画布上按顺序、以真实节奏播放。
画面下方显示会话的各项数据,既有当前观看时刻的数值,也有总计:运行了多久、经过其代理的流量(下行和上行)、打开的页面数、点击次数、滚动次数、输入的字符数,以及各项验证的结果。吞吐量图表与视频共用同一时间轴,并在图上显示播放位置;点击图表即可跳转到该处。旁边是消耗数据最多的网站,下方是会话访问互联网的方式(住宅代理、你自己的代理或直连,以及所请求的国家)、打开的连接数及其中失败的数量、代理的重试次数,以及被 adblock 拒绝的广告和跟踪器。分享链接从不显示代理地址或会话费用;你自己的仪表盘会额外显示费用。
时间线从不记录输入的文本,只记录输入的字符数以及 Enter、Tab 等按键名;视频则显示页面所显示的内容,见下文。
分享会话:先实时观看,再看回放
观看链接会在会话运行时实时显示画面,并在旁边列出它的操作;会话结束后,同一个链接会打开它的回放。打开链接无需账号,且从不允许控制:
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 适用于你的任何会话,无论是运行中还是已结束。minutes 设置链接的有效时长:1 到 20160(14 天),默认 10080(7 天)。control 不适用(400)。会话录制过时(record: true),回放播放录像;未录制时,则在空白画布上播放操作。令牌位于 # 之后,因此永远不会进入服务器日志;它会保留在页面地址中,所以可以直接把该地址转发给别人。任何持有链接的人在链接过期前都能观看会话及其回放,因此只分享给有权查看的人。其中显示的时间线会去掉页面地址中的查询字符串。在仪表盘中,实时画面里的“Share”会生成同样的链接(“Watch + replay”),已结束的会话则提供“Share replay”。
分享录像
如果只想让没有账号的人看视频,可以创建录像链接。在链接过期之前,它会打开本站上播放该录像的页面:
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": "…" }它与生成实时画面链接使用同一个 share 调用,只需加上 recording: true;minutes 设置链接的有效时长:1 到 240,默认 30,且不会超过录像的 expiresAt。尚未就绪的录像会返回 409 NOT_READY,control 不适用(400)。令牌位于 # 之后,因此永远不会进入服务器日志;转发时请保留完整链接。各类链接相互独立:录像链接不能打开实时画面,实时画面链接也不能打开回放(观看链接两者都能打开)。任何持有录像链接的人都能观看视频,因此请像对待录像本身一样对待它。
保留期限与隐私
- 录像自变为
ready起私密保存 14 天。到recording.expiresAt时,下载链接和回放链接失效,文件随后很快被删除;请在此之前下载需要保留的录像。 - 下载链接只会提供给你(通过你的 API 密钥或仪表盘),最多 5 分钟后失效;在此之前,任何持有链接的人都可以使用。
- 录像显示的是页面所显示的内容。输入到普通输入框中的任何内容都会出现在视频中,包括输入到会显示文本的输入框中的密钥。密码框与屏幕上一样显示为圆点。如果不希望保存某些任务的屏幕画面,请不要为其开启录制。
事件时间线
每个会话都会保存一条时间线。使用 GET /api/v1/browsers/<id>/events 读取,它同样适用于任务(任务的 id 就是其会话 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
}seq按顺序为会话的事件编号,从 1 开始,中间可能有空缺。at是事件发生的时间。after返回该seq之后的事件(默认 0,即从头开始);limit为 1 到 500,默认 200。超出这些范围的值会返回400。next是获取下一页时使用的after;如果你已经拿到目前保存的全部事件,则为null。- 会话运行期间,事件会随浏览器的用量报告分批到达,大约每 15 秒一次。要跟踪运行中的会话,请持续查询,并把
after设为你看到的最后一个seq。 - 每个会话最多保留 1000 条事件,此外还可保留最多 2000 条
input事件和 1500 条traffic事件;一条truncated事件标记事件开始被丢弃的位置。事件会在会话结束 2 天后删除。 input事件在操作结束后才发送,因此它的at(操作开始的时间)可能早于前一条事件。按at排序即可按实际发生顺序显示。- 实时画面会在事件发生时立即收到它们,无需等待用量报告:每条事件都通过其 WebSocket 以文本消息
{"ev": {"seq", "at", "type", "data"}}的形式到达,at以毫秒为单位(仅限分享视图可以显示的类型:不含client.connected、被拒绝的命令或主机、profile 详情以及费用)。
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"]事件类型
| type | data | 含义 |
|---|---|---|
session.started | { kind, proxy, country?, state?, city?, adblock, headless, geo? } | 浏览器已启动。由你驱动的会话,kind 为 "cdp";智能体任务则为 "run"。 |
navigation | { url, title } | 某个标签页跳转到了新地址。每个标签页每秒最多一条。 |
tab.opened | { url } | 打开了一个新标签页或弹出窗口。 |
tab.closed | {} | 关闭了一个标签页。 |
cdp.denied | { method, reason } | 托管浏览器拒绝了一条 CDP 命令,例如从服务器上传文件。每个会话最多 50 条。 |
profile.loaded | { cookies, files } | 一个已保存的 profile 被加载到浏览器中。 |
profile.saved | { cookies, bytes } | 会话结束时,profile 被保存回去。 |
run.started | { jet: { version, commit } } | Jet 开始执行任务,并注明其版本。 |
run.step | { step, kind, action, text, probability, url } | 任务中的一个步骤,与 result.steps 中的相同。text 中的密钥显示为 {{name}}。 |
run.finished | { status, detail } | Jet 已停止,附带结果的状态(done、blocked、needs_input、budget、error)。 |
handoff.requested | { reason } | 任务中的智能体请求人工介入(handoff: true)。你用 POST …/handoff 自行发起的交接不会出现在时间线中;这类交接请使用 handoff.requested webhook。 |
handoff.done | {} | 任务的人工交接被标记为完成(通过 “I'm done” 按钮、仪表盘或 API),智能体随后继续执行。 |
recording.started | { fps } | 录像的第一帧,即视频的第 0 秒。某个事件在视频中的位置等于它的 at 减去此事件的 at。fps 为帧率。 |
slider | { variant, outcome, attempt?, reason?, site } | 一次滑块验证尝试(solveSliders)。variant 为 slide 或 puzzle;outcome 为 passed(验证消失)、failed(验证仍在;attempt 记录尝试次数,每页最多三次)或 skipped,并附带 reason,表示某个拼图被保持原样,而不是凭猜测拖动。 |
checkbox | { outcome, attempt?, reason?, site } | 一次复选框验证尝试(solveCheckboxes):点击了一个“请验证你是人类”复选框。outcome 为 passed(复选框消失或已勾选)、failed(仍在等待;attempt 记录尝试次数,每页最多三次)或 skipped,并附带 reason。 |
pressHold | { outcome, attempt?, reason?, site } | 一次长按验证尝试(solvePressHold):按住一个长按验证按钮,直到它报告完成。outcome 为 passed(按钮报告完成或消失)、failed(未报告完成;因超时而结束的长按,其 reason 为 timeout,attempt 记录尝试次数)或 skipped,并附带 reason。 |
challenge.detected | { category, solvable, reason?, site } once per challenge per page, with challengeService on | 开启 challengeService 时:页面显示的一个验证,每个页面上的每个验证记录一次。包含 category(token、score、clearance、block-page、image)、solvable,以及无法求解时的 reason(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 | 向求解服务(challengeService)发出的一次请求。outcome 为 solved(答案已填入且验证消失;applied 说明填入方式:callback、field、cookie、typed、dragged、hook)、failed 或 skipped,并附带 reason(unsolved、still_there、bad_key、no_balance、budget 等)。costUsd 为该服务对此次请求收取的费用。 |
client.connected | { ip, ua } | 一个 CDP 客户端连接到了会话(重新连接时也会记录):包含会话服务器看到的地址以及客户端的 User-Agent。 |
egress.refused | { host, port, reason } | 浏览器尝试访问私有、回环或链路本地地址(reason:private、loopback、link-local、own-ip、blocked-range),或 25 等被封禁的端口(blocked-port),连接被拒绝。每个主机和端口记录一次,每个会话最多 50 条。 |
input | { kind, by, x?, y?, vw?, vh?, shown?, ms, path?, x2?, y2?, dx?, dy?, button?, n?, chars?, keys? } | 页面上的一次操作,在操作结束后发送:kind 为 click、drag、tap、scroll、type、move(指针移动后停下,未点击)或 capped(从这里起不再保存该会话的操作)。by 表示操作者:client(你的连接)、agent(任务中的智能体)、viewer(实时画面中的某个人)或 solver(验证求解器)。x、y 是页面视口 vw × vh 中的 CSS 像素;在实时画面和录像所显示的标签页上,shown 为 true,在其他标签页上为 false。path 是指针的移动轨迹,格式为 [ms from at, x, y],ms 是操作耗时。type 提供 chars(输入的字符数)和 keys(Enter、Tab 等按键名以及 Ctrl+V 等快捷键名),但从不包含输入的文本。 |
traffic | { up, down, conns, failed, retries, blocked } | 到目前为止经过会话代理的流量累计值:up 和 down 为字节数,conns 为已打开的连接数,failed 为未能建立的连接数,retries 为代理出现短暂故障后重试的隧道数,blocked 为被 adblock 拒绝的请求数。只要其中任一数值在变化,就每隔几秒发送一次;回放会将其绘制成图表。 |
limit | { reason } | 达到了某项上限:max_duration、idle_timeout、max_bytes、max_files_size(会话的文件夹已满)或 max_recording_size(只有录像停止,会话继续运行)。余额耗尽只会体现在 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? } | 会话已结束,并注明原因(与会话的 endReason 相同)。 |
truncated | {} One marker at the first event that was not kept: the session reached 1000 stored events | 从这里开始的事件已被丢弃:会话超过了 1000 条事件(input 和 traffic 事件有各自的配额),或其服务器未能及时发送事件。每个会话最多一条。 |
事件数据会保持精简:data 超过 2 KB 的事件会改为存储 { "truncated": true }。密钥从不出现在事件中;如果某个步骤输入了密钥,其 text 会显示为 {{name}}。今后可能会新增事件类型,因此遇到不认识的类型时请跳过,而不要报错。