ライブビューとセッション

ホスト型ブラウザをライブで視聴し、操作を引き継ぐか、ビューを共有します。セッションを管理し、ブラウザを動かしたままにして、あとから再接続することもできます。

ダッシュボードでセッションをクリックすると、そのトラフィックの送信先サイトを確認したり、ライブで視聴したりできます。「Take control」を押すと、自分でクリック、入力、スクロール、貼り付け、ページ移動ができます。たとえば、ログインしたり、スクリプトでは通過できないチェックを通過したりするときに使います。その間もスクリプトは接続されたままなので、操作中はスクリプトを一時停止してください。人による入力もアクティビティとみなされるため、操作中のセッションがアイドル状態として閉じられることはありません。「Share」を使うと、アカウントがなくても誰でも開けるリンクを作成できます。視聴のみか操作付きかを選べ、有効期間は 15 分から 4 時間で、セッションの終了後まで有効になることはありません。

API からは次のように行います。

bash

# a live-view WebSocket for a running session (open it within 60 s)
# binary messages are JPEG frames, text messages are {"url","title","tabs"}
curl -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/<id>/live

# with control: the answer says "interactive": true when it was granted
curl -H "authorization: Bearer cc_live_..." "https://www.clearcotelabs.com/api/v1/browsers/<id>/live?control=1"

# a share link: control optional, 1 to 240 minutes (default 30)
curl -X POST -H "authorization: Bearer cc_live_..." -H "content-type: application/json" -d '{"control": false, "minutes": 60}' https://www.clearcotelabs.com/api/v1/browsers/<id>/share

操作権限がある場合は、同じ WebSocket で JSON のテキストメッセージを送信します。座標は、表示しているフレームに対する割合（0〜1）で指定します。それ以外は無視されます。

メッセージ	動作
`{"t":"mouse","e":"down","x":0.5,"y":0.3,"b":"left","n":1,"m":0}`	押下（`down`）、解放（`up`）、または `move`。`n` はクリック回数、`m` は修飾キー（Alt 1、Ctrl 2、Meta 4、Shift 8）です。
`{"t":"wheel","x":0.5,"y":0.5,"dx":0,"dy":400}`	指定した位置で、ピクセル単位でスクロールします。
`{"t":"key","e":"down","key":"a","code":"KeyA","kc":65,"text":"a"}`	キーボードが送るのと同じ形式の、キーの押下または解放です。
`{"t":"text","text":"pasted text"}`	入力したかのようにテキストを挿入します（最大 5000 文字）。
`{"t":"nav","a":"back"}`、`forward`、`reload`、または `{"t":"nav","a":"go","url":"example.com"}`	履歴の移動、再読み込み、または http(s) アドレスを開きます。

GET /api/v1/browsers/<id> のレスポンスには traffic が含まれます。これはそのセッションのバイト数上位 20 サイトです。

セッションの管理

bash

# one session: status, traffic, seconds, cost so far
curl -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/<id>

# stop it (a running browser closes within about 15 seconds)
curl -X DELETE -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/<id>

# balance + your 20 most recent sessions
curl -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers

# filtered by status and note text, up to 100; page back with before=<a createdAt you got>
curl -H "authorization: Bearer cc_live_..." "https://www.clearcotelabs.com/api/v1/browsers?status=active,ended&note=shop-de&limit=50"

# label a session (null clears it)
curl -X PATCH -H "authorization: Bearer cc_live_..." -H "content-type: application/json" -d '{"note": "shop-de nightly"}' https://www.clearcotelabs.com/api/v1/browsers/<id>

作成時にセッションへ note を付けておくと、一覧やダッシュボードで見つけやすくなります。以前のセッションと同じサーバーで新しいセッションを起動するには（キャッシュが温まった状態の同じマシン）、そのセッションの worker を渡します。そのサーバーが満杯の場合は、別のサーバーが割り当てられるのではなく 503 が返ります。

セッションは、ブラウザを閉じたときや切断したとき、また後述の制限に達したときにも終了します。停止リクエストを送ると、誰も接続していないセッションは即座に終了します。実行中のブラウザは、1 回の報告間隔（約 15 秒）以内にサーバーによって閉じられます。GET のレスポンスは次のとおりです。

json

{
  "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 }
}

status	説明
`pending`	Created; nobody has connected yet. Counts towards the concurrency limit until it starts or expires.
`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.
`ended`	Closed: you disconnected, stopped it, or a limit or the balance ended it. endReason says which.
`expired`	Nobody connected within two minutes of creating it. Never billed.

一覧取得の GET /api/v1/browsers は、同じ形式のセッションオブジェクトを新しい順に並べた { balanceEur, sessions: [...] } を返します。

ブラウザを開いたままにして再接続する

デフォルトでは、クライアントが切断するとセッションは終了します。keepAlive: true を指定して起動すると、ブラウザはタブ、Cookie、出口 IP を保ったまま動作し続けます。そのため、後から実行するスクリプト（あるいはクラッシュ後やノート PC を閉じた後の同じスクリプト）で、前回の続きから作業を再開できます。

bash

# a new single-use connect URL for a running keepAlive session (connect within two minutes)
curl -X POST -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/<id>/connect

切断すれば実行したままにできます。Playwright の browser.close()（connectOverCDP 経由では切断するだけです）、Puppeteer の browser.disconnect()、あるいは単にプロセスを終了するだけでもかまいません。
DELETE /api/v1/browsers/<id> を送るか、CDP コマンド Browser.close を送ると終了します。Puppeteer の browser.close() はこのコマンドを送ります。Playwright では await (await browser.newBrowserCDPSession()).send("Browser.close") を使います。終了するまでは、同時実行数の枠を 1 つ占有し続けます。
接続できるクライアントは同時に 1 つだけです。別のクライアントが接続している間の再接続は 409 で拒否されます。keepAlive なしで起動したセッションへの再接続も同様です。
誰も接続していない間も、制限は適用されます。対象は idleTimeoutSec（後で戻ってくるつもりのブラウザでは、最大 1800 まで引き上げてください）、timeoutSec、maxGb、そして残高です。開いたままのページはバックグラウンドのトラフィックを読み込み続け、その分もほかと同様に課金されます。

ライブビューとセッション

ライブビュー：視聴、操作、共有

セッションの管理

ブラウザを開いたままにして再接続する