Aufzeichnungen und die Ereignis-Timeline
Zwei Wege, im Nachhinein zu sehen, was ein gehosteter Browser getan hat. Eine Aufzeichnung ist ein Video des Browser-Bildschirms. Die Ereignis-Timeline ist eine Liste dessen, was passiert ist, mit Zeitstempeln: Seiten, Tabs, Klicks, Scrollen und Tippen, was die Challenge-Solver entschieden haben, Agent-Schritte, Übergaben und Limits. Die Wiedergabe verbindet beides: das Video mit jeder Aktion darübergelegt. Das alles funktioniert für Sessions, die Sie selbst steuern, und für Agent-Runs.
Eine Session aufzeichnen
Übergeben Sie record: true, wenn Sie die Session oder den Run erstellen. Die Aufzeichnung ist standardmäßig aus.
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}'- Das Video zeigt wie die Live-Ansicht den aktiven Tab, mit wenigen Bildern pro Sekunde, als H.264-MP4 in 1280×800 (andere Fenstergrößen erhalten schwarze Balken). Es ist dafür gedacht, zu sehen, was passiert ist, nicht für eine flüssige Wiedergabe.
- Die Aufzeichnung endet, wenn die Session endet oder die Datei eine Größenobergrenze erreicht; die Session selbst läuft weiter.
- Sie wird nicht als Traffic abgerechnet: Die Bilder werden auf unserem Server erfasst, nicht aus dem Internet heruntergeladen.
- Nur manche Server können aufzeichnen. Eine Session mit
record: truewird nur auf einem solchen gestartet; ist keiner frei, erhalten Sie das übliche503.
Status
Die Session-Ansicht (GET /api/v1/browsers/<id> und die session eines Runs) hat ein Feld recording: null, wenn die Session nicht aufgezeichnet wurde, sonst:
"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 und expiresAt sind null, bis die Aufzeichnung ready ist.
| status | Bedeutung |
|---|---|
recording | Die Session läuft und wird aufgezeichnet. |
processing | Die Session ist beendet; die Datei wird fertiggestellt und hochgeladen. |
ready | Sie können sie herunterladen oder teilen. |
failed | Die Aufzeichnung konnte nicht erstellt oder hochgeladen werden: Die Session ist nie gestartet, der Server konnte die Datei nicht fertigstellen, oder sie war 25 Stunden nach dem Ende der Session immer noch nicht eingetroffen. Es gibt keine Datei. |
expired | Die Aufbewahrungsfrist ist abgelaufen: Die Datei ist gelöscht. |
Die Datei wird hochgeladen, sobald die Session beendet ist; eine Aufzeichnung wird also etwas später als die Session ready, eine lange dauert länger. Ist sie 25 Stunden nach dem Ende der Session immer noch nicht eingetroffen, wird sie als failed markiert. Wenn Sie lieber benachrichtigt werden, statt abzufragen, richten Sie einen recording.ready-Webhook ein.
Herunterladen
GET /api/v1/browsers/<id>/recording antwortet mit einer 302-Weiterleitung auf einen privaten Download-Link, der höchstens 5 Minuten lang funktioniert. Folgen Sie ihm sofort, statt ihn zu speichern. Solange die Aufzeichnung recording oder processing ist, lautet die Antwort 409 mit dem Code NOT_READY; eine Session, die nicht aufgezeichnet wurde, deren Aufzeichnung fehlgeschlagen oder abgelaufen ist, ergibt ein 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 linkDas Dashboard spielt die Aufzeichnung neben den Details der Session als Wiedergabe ab.
Die Wiedergabe
Eine Wiedergabe spielt die Aufzeichnung ab und legt die Timeline der Session darüber: den Zeiger und seinen Weg, einen Ring, wo jeder Klick gelandet ist, den Weg jedes Ziehens (auch eines Sliders, den der Solver gezogen hat), jedes Scrollen und jede Tippfolge, die geöffnete Seite, was die Challenge-Solver entschieden haben, und die Schritte des Agents als Untertitel. Daneben die Aktivitätsliste: Klicken Sie auf eine Zeile, um dorthin zu springen; die Zeile des aktuellen Moments folgt dem Video. Beschleunigen Sie die Wiedergabe oder überspringen Sie die Abschnitte, in denen nichts passiert. Auch eine Session, die nicht aufgezeichnet wurde, lässt sich wiedergeben: Ihre Aktionen laufen dann auf einer leeren Bühne ab, in ihrer Reihenfolge und in ihrem echten Tempo.
Unter dem Bild die Kennzahlen der Session, zum gerade angesehenen Zeitpunkt und insgesamt: wie lange sie gelaufen ist, wie viel über ihren Proxy ging (Download und Upload), die geöffneten Seiten, die Klicks, das Scrollen und die getippten Zeichen und wie ihre Challenges ausgingen. Ein Durchsatzdiagramm zeigt den Traffic auf derselben Zeitachse wie das Video, mit dem Abspielkopf darauf; klicken Sie in das Diagramm, um dorthin zu springen. Daneben die Sites, die die meisten Daten verbraucht haben, und darunter, wie die Session ins Internet gelangt ist (Residential, Ihr eigener Proxy oder direkt, mit dem angefragten Land), die geöffneten Verbindungen und wie viele davon fehlschlugen, die Wiederholungsversuche des Proxys und die Werbung und Tracker, die adblock abgelehnt hat. Ein geteilter Link zeigt nie die Adresse des Proxys oder die Kosten der Session; Ihr Dashboard zeigt zusätzlich die Kosten.
Getippter Text wird nie in der Timeline festgehalten, nur wie viele Zeichen getippt wurden und die Namen von Tasten wie Enter oder Tab; das Video zeigt, was die Seite gezeigt hat, siehe unten.
Eine Session teilen: erst live, dann ihre Wiedergabe
Ein Watch-Link zeigt die Session live, solange sie läuft, mit einer Liste ihrer Aktionen daneben, und nach ihrem Ende öffnet derselbe Link ihre Wiedergabe. Zum Öffnen ist kein Account nötig, und er erlaubt nie die Steuerung:
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 funktioniert für jede Ihrer Sessions, laufend oder beendet. minutes legt fest, wie lange der Link funktioniert: 1 bis 20160 (14 Tage), Standard 10080 (7 Tage). control gilt hier nicht (400). Die Wiedergabe spielt die Aufzeichnung ab, wenn die Session aufgezeichnet wurde (record: true), und sonst die Aktionen auf einer leeren Bühne. Das Token steht hinter dem #, gelangt also nie in ein Server-Log, und es bleibt in der Adresse der Seite, sodass sich die Adresse unverändert weitergeben lässt. Wer den Link hat, kann die Session und ihre Wiedergabe ansehen, bis er abläuft; teilen Sie ihn also nur mit Personen, die sie sehen dürfen. Die angezeigte Timeline nennt Seitenadressen ohne ihren Query-String. Im Dashboard erzeugt Share in der Live-Ansicht denselben Link (Watch + replay), und eine beendete Session hat Share replay.
Eine Aufzeichnung teilen
Um jemandem ohne Account nur das Video zu zeigen, erstellen Sie einen Aufzeichnungs-Link. Er öffnet auf dieser Website eine Seite, die das Video abspielt, bis der Link abläuft:
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": "…" }Es ist derselbe share-Aufruf wie für einen Live-Ansicht-Link, mit recording: true; minutes legt fest, wie lange der Link funktioniert: 1 bis 240, Standard 30, und nie über das expiresAt der Aufzeichnung hinaus. Eine Aufzeichnung, die noch nicht fertig ist, antwortet mit 409 NOT_READY, und control gilt hier nicht (400). Das Token steht hinter dem #, gelangt also nie in ein Server-Log; geben Sie den Link vollständig weiter. Die Link-Arten bleiben getrennt: Ein Aufzeichnungs-Link kann keine Live-Ansicht öffnen und ein Live-Ansicht-Link keine Wiedergabe (ein Watch-Link öffnet beides). Wer einen Aufzeichnungs-Link hat, kann das Video ansehen; behandeln Sie ihn also wie die Aufzeichnung selbst.
Aufbewahrung und Datenschutz
- Aufzeichnungen werden 14 Tage lang privat gespeichert, gerechnet ab dem Zeitpunkt, an dem sie
readywerden. Zurecording.expiresAtfunktionieren Download- und Wiedergabe-Links nicht mehr, und die Datei wird bald danach gelöscht; laden Sie vorher herunter, was Sie behalten möchten. - Download-Links erhalten nur Sie (über Ihren API-Schlüssel oder das Dashboard), und sie funktionieren höchstens 5 Minuten lang; bis dahin kann jeder, der einen hat, ihn verwenden.
- Eine Aufzeichnung zeigt, was die Seite gezeigt hat. Alles, was in ein gewöhnliches Feld getippt wird, ist im Video zu sehen, auch ein Secret, das in ein Feld getippt wird, das seinen Text anzeigt. Passwortfelder zeigen Punkte, wie auf dem Bildschirm. Lassen Sie die Aufzeichnung bei Runs aus, deren Bildschirme nicht gespeichert werden sollen.
Die Ereignis-Timeline
Jede Session führt eine Timeline. Lesen Sie sie mit GET /api/v1/browsers/<id>/events aus; das funktioniert auch für Runs (die ID eines Runs ist seine 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
}seqnummeriert die Ereignisse einer Session der Reihe nach, ab 1; es kann Lücken geben.atist der Zeitpunkt, zu dem es geschah.afterliefert die Ereignisse nach dieserseq(Standard 0, der Anfang);limitist 1 bis 500, Standard 200. Werte außerhalb dieser Bereiche ergeben ein400.nextist dasafterfür die nächste Seite, odernull, wenn Sie alles haben, was bisher gespeichert ist.- Während eine Session läuft, treffen ihre Ereignisse gebündelt mit den Nutzungsberichten des Browsers ein, etwa alle 15 Sekunden. Um einer laufenden Session zu folgen, fragen Sie immer wieder ab, mit
afterauf die letzteseqgesetzt, die Sie gesehen haben. - Eine Session behält höchstens 1000 Ereignisse und zusätzlich bis zu 2000
input- und 1500traffic-Ereignisse; ein einzelnestruncated-Ereignis markiert, wo Ereignisse verworfen wurden. Ereignisse werden 2 Tage nach dem Ende der Session gelöscht. - Ein
input-Ereignis wird gesendet, sobald die Aktion abgeschlossen ist; seinat(der Beginn der Aktion) kann daher vor dem des vorherigen Ereignisses liegen. Sortieren Sie nachat, um die Reihenfolge zu zeigen, in der die Dinge geschahen. - Eine Live-Ansicht erhält die Ereignisse, sobald sie passieren, ohne auf einen Nutzungsbericht zu warten: Jedes kommt auf ihrem WebSocket als Textnachricht
{"ev": {"seq", "at", "type", "data"}}an, mitatin Millisekunden (nur die Arten, die eine geteilte Ansicht zeigen darf: keinclient.connected, keine abgelehnten Befehle oder Hosts, keine Profildetails und keine Kosten).
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"]Ereignistypen
| type | data | Bedeutung |
|---|---|---|
session.started | { kind, proxy, country?, state?, city?, adblock, headless, geo? } | Der Browser läuft. kind ist "cdp" für eine Session, die Sie steuern, und "run" für einen Agent-Run. |
navigation | { url, title } | Ein Tab hat eine neue Adresse aufgerufen. Höchstens eines pro Sekunde und Tab. |
tab.opened | { url } | Ein neuer Tab oder ein Pop-up wurde geöffnet. |
tab.closed | {} | Ein Tab wurde geschlossen. |
cdp.denied | { method, reason } | Der gehostete Browser hat einen CDP-Befehl abgelehnt, zum Beispiel einen Datei-Upload vom Server. Höchstens 50 pro Session. |
profile.loaded | { cookies, files } | Ein gespeichertes Profil wurde in den Browser geladen. |
profile.saved | { cookies, bytes } | Das Profil wurde am Ende der Session zurückgespeichert. |
run.started | { jet: { version, commit } } | Jet hat mit einem Run begonnen, und in welcher Version. |
run.step | { step, kind, action, text, probability, url } | Ein Schritt eines Runs, wie in result.steps. Secrets in text erscheinen als {{name}}. |
run.finished | { status, detail } | Jet hat aufgehört, mit dem Status des Ergebnisses (done, blocked, needs_input, budget, error). |
handoff.requested | { reason } | Der Agent eines Runs hat nach einem Menschen gefragt (handoff: true). Eine Übergabe, die Sie selbst mit POST …/handoff starten, steht nicht in der Timeline; nutzen Sie dafür den Webhook handoff.requested. |
handoff.done | {} | Die Übergabe eines Runs wurde als erledigt markiert (die Schaltfläche „I'm done“, das Dashboard oder die API), und der Agent hat weitergemacht. |
recording.started | { fps } | Das erste Bild der Aufzeichnung: die 0 s des Videos. Die Position eines Ereignisses im Video ist sein at minus das at dieses Ereignisses. fps ist die Bildrate. |
slider | { variant, outcome, attempt?, reason?, site } | Ein Versuch an einer Slider-Challenge (solveSliders). variant ist slide oder puzzle; outcome ist passed (die Challenge ist verschwunden), failed (sie war noch da; attempt zählt die Versuche, höchstens drei pro Seite) oder skipped, mit einem reason, wenn ein Puzzle in Ruhe gelassen statt auf gut Glück gezogen wurde. |
checkbox | { outcome, attempt?, reason?, site } | Ein Versuch an einer Checkbox-Challenge (solveCheckboxes): Ein „Bestätigen Sie, dass Sie ein Mensch sind“-Kästchen wurde angeklickt. outcome ist passed (das Kästchen ist verschwunden oder wurde angehakt), failed (es wartete noch; attempt zählt die Versuche, höchstens drei pro Seite) oder skipped, mit einem reason. |
pressHold | { outcome, attempt?, reason?, site } | Ein Versuch an einer Press-and-Hold-Challenge (solvePressHold): Eine Press-and-Hold-Schaltfläche zur Verifizierung wurde gedrückt gehalten, bis sie den Abschluss meldete. outcome ist passed (die Schaltfläche hat den Abschluss gemeldet oder ist verschwunden), failed (sie hat es nicht; ein Halten, dem die Zeit ausging, hat den reason timeout, und attempt zählt die Versuche) oder skipped, mit einem reason. |
challenge.detected | { category, solvable, reason?, site } once per challenge per page, with challengeService on | Mit eingeschaltetem challengeService: eine Challenge, die die Seite gezeigt hat, einmal pro Challenge und Seite. category (token, score, clearance, block-page, image), solvable und ein reason, wenn sie es nicht ist (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 | Eine Anfrage an den Lösungsdienst (challengeService). outcome ist solved (die Antwort wurde eingesetzt und die Challenge ist verschwunden; applied sagt, wie: callback, field, cookie, typed, dragged, hook), failed oder skipped, mit einem reason (unsolved, still_there, bad_key, no_balance, budget, ...). costUsd ist, was der Dienst dafür berechnet hat. |
client.connected | { ip, ua } | Ein CDP-Client hat sich mit der Session verbunden (auch bei einer erneuten Verbindung): die Adresse, die der Server der Session gesehen hat, und der User-Agent des Clients. |
egress.refused | { host, port, reason } | Der Browser hat versucht, eine private, Loopback- oder Link-Local-Adresse (reason: private, loopback, link-local, own-ip, blocked-range) oder einen gesperrten Port wie 25 (blocked-port) zu erreichen, und die Verbindung wurde abgelehnt. Einmal pro Host und Port, höchstens 50 pro Session. |
input | { kind, by, x?, y?, vw?, vh?, shown?, ms, path?, x2?, y2?, dx?, dy?, button?, n?, chars?, keys? } | Eine Aktion auf der Seite, sobald sie abgeschlossen ist: kind ist click, drag, tap, scroll, type, move (der Zeiger hat sich bewegt und ist ohne Klick stehen geblieben) oder capped (ab hier werden die Aktionen der Session nicht mehr festgehalten). by gibt an, wer gehandelt hat: client (Ihre Verbindung), agent (der Agent eines Runs), viewer (ein Mensch in der Live-Ansicht) oder solver (die Challenge-Solver). x, y sind CSS-Pixel im Viewport vw × vh der Seite; shown ist true auf dem Tab, den Live-Ansicht und Aufzeichnung zeigen, und false auf einem anderen Tab. path ist der Weg des Zeigers als [ms from at, x, y], ms die Dauer der Aktion. type liefert chars, die Anzahl der getippten Zeichen, und keys, die Namen von Tasten wie Enter oder Tab und von Tastenkürzeln wie Ctrl+V; nie den Text. |
traffic | { up, down, conns, failed, retries, blocked } | Was bisher über den Proxy der Session gelaufen ist, kumuliert: up und down in Bytes, conns geöffnete Verbindungen, failed Verbindungen, die nicht zustande kamen, retries Tunnel, die nach einem Aussetzer des Proxys erneut versucht wurden, blocked von adblock abgelehnte Requests. Alle paar Sekunden, solange sich einer der Werte ändert; die Wiedergabe zeigt ihn als Diagramm. |
limit | { reason } | Ein Limit wurde erreicht: max_duration, idle_timeout, max_bytes, max_files_size (der Dateiordner der Session ist voll) oder max_recording_size (nur die Aufzeichnung wurde beendet; die Session läuft weiter). Ein aufgebrauchtes Guthaben zeigt sich nur 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? } | Die Session ist beendet, und warum (dasselbe wie der endReason der Session). |
truncated | {} One marker at the first event that was not kept: the session reached 1000 stored events | Ab hier wurden Ereignisse verworfen: Die Session hat 1000 Ereignisse überschritten (input- und traffic-Ereignisse haben eigene Kontingente), oder ihr Server konnte sie nicht rechtzeitig senden. Höchstens eines pro Session. |
Ereignisdaten werden klein gehalten: Bei einem Ereignis, dessen data größer als 2 KB ist, wird stattdessen { "truncated": true } gespeichert. Secrets erscheinen nie in Ereignissen; wo ein Schritt eines getippt hat, zeigt sein text {{name}}. Es können neue Ereignistypen hinzukommen; überspringen Sie also Typen, die Sie nicht kennen, statt daran zu scheitern.