録画とイベントタイムライン
ホスト型ブラウザが何をしたかを後から確認する方法は 2 つあります。録画はブラウザ画面の動画です。イベントタイムラインは、起きたことをタイムスタンプ付きで並べたリストです。ページ、タブ、クリック、スクロール、入力、チャレンジのソルバーの判断、エージェントのステップ、引き継ぎ、上限到達などが含まれます。リプレイはこの 2 つを組み合わせたもので、動画の上にすべての操作を重ねて表示します。いずれも、自分で操作するセッションとエージェントの実行の両方で使えます。
セッションを録画する
セッションまたは実行を作成するときに 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
}bytes、durationSec、expiresAt は、録画が ready になるまで null です。
| status | 意味 |
|---|---|
recording | セッションが実行中で、録画されています。 |
processing | セッションは終了しました。ファイルを仕上げてアップロードしています。 |
ready | ダウンロードや共有ができます。 |
failed | 録画を作成またはアップロードできませんでした。セッションが開始しなかった、サーバーがファイルを仕上げられなかった、またはセッション終了から 25 時間経ってもファイルが届かなかった場合です。ファイルはありません。 |
expired | 保存期間を過ぎ、ファイルは削除されています。 |
ファイルはセッションの終了後にアップロードされるため、録画はセッションより少し遅れて ready になります。長い録画ほど時間がかかります。セッション終了から 25 時間経っても届かない場合は failed になります。ポーリングする代わりに通知を受け取るには、recording.ready のWebhook を追加してください。
ダウンロード
GET /api/v1/browsers/<id>/recording は、最長 5 分間有効な非公開のダウンロードリンクへの 302 リダイレクトを返します。リンクは保存せず、すぐにたどってください。録画が recording または processing の間は、コード NOT_READY 付きの 409 が返ります。録画されていないセッション、録画に失敗したセッション、録画の期限が切れたセッションでは 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 秒ごと)。実行中のセッションを追うには、最後に見た
seqをafterに指定して問い合わせを繰り返します。 - 1 つのセッションが保持するイベントは最大 1000 件で、それとは別に
inputイベントを最大 2000 件、trafficイベントを最大 1500 件保持します。イベントが破棄された位置にはtruncatedイベントが 1 件記録されます。イベントはセッション終了の 2 日後に削除されます。 inputイベントは操作が終わった時点で送られるため、そのat(操作が始まった時刻)が直前のイベントより前になることがあります。起きた順に表示するにはatで並べ替えてください。- ライブビューでは、使用量レポートを待たずにイベントが発生と同時に届きます。各イベントは WebSocket 上のテキストメッセージ
{"ev": {"seq", "at", "type", "data"}}として届き、atはミリ秒単位です(共有ビューで表示できる種類に限られます。client.connected、拒否されたコマンドやホスト、プロファイルの詳細、費用は含まれません)。
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 } | タブが新しいアドレスに移動しました。タブごとに 1 秒あたり最大 1 件です。 |
tab.opened | { url } | 新しいタブまたはポップアップが開きました。 |
tab.closed | {} | タブが閉じました。 |
cdp.denied | { method, reason } | ホスト型ブラウザが CDP コマンドを拒否しました(たとえばサーバーからのファイルアップロード)。セッションあたり最大 50 件です。 |
profile.loaded | { cookies, files } | 保存済みのプロファイルがブラウザに読み込まれました。 |
profile.saved | { cookies, bytes } | セッションの終了時にプロファイルが保存し直されました。 |
run.started | { jet: { version, commit } } | Jet が実行を開始しました。そのバージョンも含みます。 |
run.step | { step, kind, action, text, probability, url } | 実行の 1 ステップで、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 が回数を数え、ページごとに最大 3 回)、skipped(reason 付き。パズルを当て推量でドラッグせずにそのままにした場合)のいずれかです。 |
checkbox | { outcome, attempt?, reason?, site } | チェックボックスチャレンジ(solveCheckboxes)への試行です。「人間であることを確認してください」のボックスがクリックされました。outcome は passed(ボックスが消えた、またはチェックが付いた)、failed(まだ待機中だった。attempt が回数を数え、ページごとに最大 3 回)、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 が有効な場合に、ページが表示したチャレンジです。ページごと、チャレンジごとに 1 回送られます。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)への 1 回の依頼です。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)に接続しようとし、その接続が拒否されました。ホストとポートの組み合わせごとに 1 回、セッションあたり最大 50 件です。 |
input | { kind, by, x?, y?, vw?, vh?, shown?, ms, path?, x2?, y2?, dx?, dy?, button?, n?, chars?, keys? } | ページ上の 1 つの操作で、操作が終わった時点で送られます。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 のイベントには別枠があります)か、サーバーがイベントを時間内に送れなかった場合です。セッションあたり最大 1 件です。 |
イベントのデータは小さく保たれます。data が 2 KB を超えるイベントには、代わりに { "truncated": true } が保存されます。シークレットがイベントに含まれることはありません。ステップでシークレットを入力した場合、その text には {{name}} と表示されます。新しいイベントの種類が追加されることがあるため、知らない種類はエラーにせずスキップしてください。