Enregistrements et chronologie des événements
Deux façons de voir après coup ce qu’a fait un navigateur hébergé. Un enregistrement est une vidéo de l’écran du navigateur. La chronologie des événements est la liste horodatée de ce qui s’est passé : pages, onglets, clics, défilements et saisie, décisions des solveurs de défis, étapes de l’agent, passages de relais et limites. La relecture réunit les deux : la vidéo avec chaque action dessinée par-dessus. Tout cela fonctionne pour les sessions que vous pilotez et pour les exécutions d’agent.
Enregistrer une session
Passez record: true lorsque vous créez la session ou l’exécution. L’enregistrement est désactivé par défaut.
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}'- La vidéo montre l’onglet actif, comme la vue en direct, à quelques images par seconde, dans un MP4 H.264 en 1280×800 (les autres tailles de fenêtre sont affichées avec des bandes noires). Elle sert à voir ce qui s’est passé, pas à offrir une lecture fluide.
- L’enregistrement s’arrête à la fin de la session, ou lorsque le fichier atteint une taille maximale ; la session elle-même continue.
- Il n’est pas facturé comme du trafic : les images sont capturées sur notre serveur, pas téléchargées depuis Internet.
- Seuls certains serveurs peuvent enregistrer. Une session avec
record: truen’est démarrée que sur l’un d’eux ; si aucun n’est libre, vous obtenez le503habituel.
Statut
La vue de la session (GET /api/v1/browsers/<id>, et la session d’une exécution) comporte un champ recording : null lorsque la session n’a pas été enregistrée, sinon :
"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 et expiresAt valent null tant que l’enregistrement n’est pas ready.
| status | Signification |
|---|---|
recording | La session est en cours et enregistrée. |
processing | La session est terminée ; le fichier est en cours de finalisation et d’envoi. |
ready | Vous pouvez le télécharger ou le partager. |
failed | L’enregistrement n’a pas pu être réalisé ou envoyé : la session n’a jamais démarré, le serveur n’a pas pu finaliser le fichier, ou celui-ci n’était toujours pas arrivé 25 heures après la fin de la session. Il n’y a pas de fichier. |
expired | Sa durée de conservation est dépassée : le fichier est supprimé. |
Le fichier est envoyé une fois la session terminée : un enregistrement passe donc à ready un peu après la session, et un long enregistrement prend plus de temps. S’il n’est toujours pas arrivé 25 heures après la fin de la session, il est marqué failed. Pour être prévenu au lieu d’interroger l’API, ajoutez un webhook recording.ready.
Télécharger
GET /api/v1/browsers/<id>/recording répond par une redirection 302 vers un lien de téléchargement privé valable 5 minutes au plus. Suivez-le immédiatement plutôt que de le stocker. Tant que l’enregistrement est recording ou processing, la réponse est un 409 avec le code NOT_READY ; une session qui n’a pas été enregistrée, dont l’enregistrement a échoué ou a expiré renvoie un 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 linkLe tableau de bord lit l’enregistrement à côté des détails de la session, sous forme de relecture.
La relecture
Une relecture lit l’enregistrement avec la chronologie de la session dessinée par-dessus : le pointeur et son trajet, un cercle à l’endroit de chaque clic, le tracé de chaque glisser (y compris un curseur que le solveur a fait glisser), chaque défilement et chaque rafale de saisie, la page qui s’est ouverte, les décisions des solveurs de défis et les étapes de l’agent en sous-titres. À côté, la liste d’activité : cliquez sur une ligne pour y sauter, et la ligne du moment suit la vidéo. Accélérez-la, ou sautez les passages où rien ne se passe. Une session qui n’a pas été enregistrée peut aussi être relue : ses actions se jouent alors sur une scène vide, dans l’ordre et à leur rythme réel.
Sous l’image, les chiffres de la session, au moment que vous regardez et au total : sa durée, le volume passé par son proxy (descendant et montant), les pages ouvertes, les clics, les défilements et les caractères saisis, et l’issue de ses défis. Un graphique de débit montre le trafic sur la même horloge que la vidéo, avec la tête de lecture dessus ; cliquez sur le graphique pour y sauter. À côté, les sites qui ont consommé le plus de données, et en dessous, la façon dont la session a atteint Internet (résidentiel, votre propre proxy ou direct, avec le pays demandé), les connexions ouvertes et combien ont échoué, les nouvelles tentatives du proxy, et les publicités et traceurs refusés par adblock. Un lien partagé n’affiche jamais l’adresse du proxy ni le coût de la session ; votre tableau de bord y ajoute le coût.
Le texte saisi n’est jamais conservé dans la chronologie, seulement le nombre de caractères saisis et les noms de touches comme Enter ou Tab ; la vidéo montre ce que la page affichait, comme expliqué plus bas.
Partager une session : en direct, puis sa relecture
Un lien de visionnage montre la session en direct tant qu’elle tourne, avec la liste de ce qu’elle fait à côté, et une fois terminée, le même lien ouvre sa relecture. Aucun compte n’est nécessaire pour l’ouvrir, et il ne donne jamais le contrôle :
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 fonctionne pour toutes vos sessions, en cours ou terminées. minutes fixe la durée de validité du lien : de 1 à 20160 (14 jours), 10080 par défaut (7 jours). control ne s’applique pas (400). La relecture lit l’enregistrement si la session a été enregistrée (record: true), et sinon les actions sur une scène vide. Le jeton se trouve après le # : il n’atteint donc jamais un log de serveur, et il reste dans l’adresse de la page, qu’on peut ainsi transmettre telle quelle. Toute personne qui détient le lien peut regarder la session et sa relecture jusqu’à son expiration : ne le partagez qu’avec des personnes autorisées à la voir. La chronologie affichée donne les adresses des pages sans leur query string. Dans le tableau de bord, « Share » dans la vue en direct crée le même lien (« Watch + replay »), et une session terminée propose « Share replay ».
Partager un enregistrement
Pour ne montrer que la vidéo à quelqu’un qui n’a pas de compte, créez un lien d’enregistrement. Il ouvre sur ce site une page qui la lit, jusqu’à l’expiration du lien :
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": "…" }C’est le même appel share que pour un lien de vue en direct, avec recording: true ; minutes fixe la durée de validité du lien : de 1 à 240, 30 par défaut, et jamais au-delà du expiresAt de l’enregistrement. Un enregistrement qui n’est pas encore prêt répond 409 NOT_READY, et control ne s’applique pas (400). Le jeton se trouve après le # : il n’atteint donc jamais un log de serveur ; transmettez le lien en entier. Les types de lien restent séparés : un lien d’enregistrement ne peut pas ouvrir une vue en direct, et un lien de vue en direct ne peut pas ouvrir une relecture (un lien de visionnage ouvre les deux). Toute personne qui détient un lien d’enregistrement peut regarder la vidéo : traitez-le comme l’enregistrement lui-même.
Conservation et confidentialité
- Les enregistrements sont stockés en privé pendant 14 jours à partir du moment où ils passent à
ready. Àrecording.expiresAt, les liens de téléchargement et de relecture cessent de fonctionner et le fichier est supprimé peu après ; téléchargez avant ce moment ce que vous voulez garder. - Les liens de téléchargement ne sont remis qu’à vous (votre clé API ou le tableau de bord) et cessent de fonctionner au bout de 5 minutes au plus ; d’ici là, quiconque en détient un peut l’utiliser.
- Un enregistrement montre ce que la page affichait. Tout ce qui est saisi dans un champ ordinaire figure dans la vidéo, y compris un secret saisi dans un champ qui affiche son texte. Les champs de mot de passe affichent des points, comme à l’écran. Laissez l’enregistrement désactivé pour les exécutions dont vous ne voulez pas que les écrans soient stockés.
La chronologie des événements
Chaque session tient une chronologie. Lisez-la avec GET /api/v1/browsers/<id>/events, qui fonctionne aussi pour les exécutions (l’id d’une exécution est l’id de sa session) :
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
}seqnumérote dans l’ordre les événements d’une session, à partir de 1 ; il peut y avoir des trous.atindique quand l’événement s’est produit.afterrenvoie les événements qui suivent ceseq(0 par défaut, le début) ;limitva de 1 à 500, 200 par défaut. Les valeurs hors de ces plages renvoient un400.nextest leafterde la page suivante, ounulllorsque vous avez tout ce qui est stocké jusqu’ici.- Pendant qu’une session tourne, ses événements arrivent par lots avec les rapports d’utilisation du navigateur, environ toutes les 15 secondes. Pour suivre une session en direct, continuez d’interroger l’API avec
afterégal au dernierseqque vous avez vu. - Une session conserve au plus 1000 événements, plus jusqu’à 2000 événements
inputet 1500traffic; un unique événementtruncatedmarque l’endroit où des événements ont été abandonnés. Les événements sont supprimés 2 jours après la fin de la session. - Un événement
inputest envoyé une fois l’action terminée : sonat(le début de l’action) peut donc précéder celui de l’événement d’avant. Triez paratpour afficher l’ordre dans lequel les choses se sont produites. - Une vue en direct reçoit les événements au fur et à mesure, sans attendre un rapport d’utilisation : chacun arrive sur son WebSocket sous forme de message texte
{"ev": {"seq", "at", "type", "data"}}, avecaten millisecondes (uniquement les types qu’une vue partagée peut afficher : pas declient.connected, de commandes ou d’hôtes refusés, de détails du profil ni de coûts).
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"]Types d’événements
| type | data | Signification |
|---|---|---|
session.started | { kind, proxy, country?, state?, city?, adblock, headless, geo? } | Le navigateur est prêt. kind vaut "cdp" pour une session que vous pilotez, "run" pour une exécution d’agent. |
navigation | { url, title } | Un onglet est passé à une nouvelle adresse. Au plus un par seconde et par onglet. |
tab.opened | { url } | Un nouvel onglet ou une fenêtre pop-up s’est ouvert. |
tab.closed | {} | Un onglet s’est fermé. |
cdp.denied | { method, reason } | Le navigateur hébergé a refusé une commande CDP, par exemple un envoi de fichier depuis le serveur. Au plus 50 par session. |
profile.loaded | { cookies, files } | Un profil enregistré a été chargé dans le navigateur. |
profile.saved | { cookies, bytes } | Le profil a été réenregistré à la fin de la session. |
run.started | { jet: { version, commit } } | Jet a commencé une exécution, et avec quelle version. |
run.step | { step, kind, action, text, probability, url } | Une étape d’une exécution, comme dans result.steps. Les secrets dans text apparaissent sous la forme {{name}}. |
run.finished | { status, detail } | Jet s’est arrêté, avec le statut du résultat (done, blocked, needs_input, budget, error). |
handoff.requested | { reason } | L’agent d’une exécution a demandé l’intervention d’une personne (handoff: true). Un passage de relais que vous lancez avec POST …/handoff n’apparaît pas dans la chronologie ; utilisez pour ceux-là le webhook handoff.requested. |
handoff.done | {} | Le passage de relais d’une exécution a été marqué comme terminé (le bouton « I'm done », le tableau de bord ou l’API) et l’agent a repris. |
recording.started | { fps } | La première image de l’enregistrement : le 0 s de la vidéo. La position d’un événement dans la vidéo est son at moins celui de cet événement. fps est la fréquence d’images. |
slider | { variant, outcome, attempt?, reason?, site } | Une tentative sur un défi à curseur (solveSliders). variant vaut slide ou puzzle ; outcome vaut passed (le défi a disparu), failed (il était toujours là ; attempt compte les tentatives, au plus trois par page) ou skipped, avec un reason, quand un puzzle a été laissé tel quel plutôt que glissé au hasard. |
checkbox | { outcome, attempt?, reason?, site } | Une tentative sur un défi à case à cocher (solveCheckboxes) : une case « vérifiez que vous êtes humain » a été cliquée. outcome vaut passed (la case a disparu ou a été cochée), failed (elle attendait toujours ; attempt compte les tentatives, au plus trois par page) ou skipped, avec un reason. |
pressHold | { outcome, attempt?, reason?, site } | Une tentative sur un défi à appui maintenu (solvePressHold) : un bouton de vérification à appui maintenu a été maintenu jusqu’à ce qu’il signale la fin. outcome vaut passed (le bouton a signalé la fin ou a disparu), failed (il ne l’a pas fait ; un appui qui a manqué de temps a le reason timeout, et attempt compte les essais) ou skipped, avec un reason. |
challenge.detected | { category, solvable, reason?, site } once per challenge per page, with challengeService on | Avec challengeService activé : un défi affiché par la page, une fois par défi et par page. category (token, score, clearance, block-page, image), solvable, et un reason quand il ne l’est pas (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 | Une demande au service de résolution (challengeService). outcome vaut solved (la réponse a été appliquée et le défi a disparu ; applied indique comment : callback, field, cookie, typed, dragged, hook), failed ou skipped, avec un reason (unsolved, still_there, bad_key, no_balance, budget, ...). costUsd est ce que le service a facturé pour cette demande. |
client.connected | { ip, ua } | Un client CDP s’est connecté à la session (y compris lors d’une reconnexion) : l’adresse vue par le serveur de la session et le User-Agent du client. |
egress.refused | { host, port, reason } | Le navigateur a tenté de joindre une adresse privée, de loopback ou link-local (reason : private, loopback, link-local, own-ip, blocked-range) ou un port bloqué comme le 25 (blocked-port), et la connexion a été refusée. Une fois par hôte et par port, au plus 50 par session. |
input | { kind, by, x?, y?, vw?, vh?, shown?, ms, path?, x2?, y2?, dx?, dy?, button?, n?, chars?, keys? } | Une action sur la page, une fois terminée : kind vaut click, drag, tap, scroll, type, move (le pointeur a bougé puis s’est arrêté sans clic) ou capped (les actions de la session cessent d’être conservées ici). by indique qui a agi : client (votre connexion), agent (l’agent d’une exécution), viewer (une personne dans la vue en direct) ou solver (les solveurs de défis). x, y sont des pixels CSS dans le viewport vw × vh de la page ; shown vaut true sur l’onglet que montrent la vue en direct et l’enregistrement, false sur un autre onglet. path est le trajet du pointeur sous la forme [ms from at, x, y], ms la durée de l’action. type donne chars, le nombre de caractères saisis, et keys, les noms de touches comme Enter ou Tab et de raccourcis comme Ctrl+V ; jamais le texte. |
traffic | { up, down, conns, failed, retries, blocked } | Ce qui est passé jusqu’ici par le proxy de la session, en cumul : up et down en octets, conns connexions ouvertes, failed connexions qui n’ont pas pu être établies, retries tunnels retentés après un raté du proxy, blocked requêtes refusées par adblock. Toutes les quelques secondes tant que l’une de ces valeurs change ; la relecture en trace le graphique. |
limit | { reason } | Une limite a été atteinte : max_duration, idle_timeout, max_bytes, max_files_size (le dossier de fichiers de la session est plein) ou max_recording_size (seul l’enregistrement s’est arrêté ; la session continue). Un solde épuisé n’apparaît que dans 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? } | La session s’est terminée, et pourquoi (identique au endReason de la session). |
truncated | {} One marker at the first event that was not kept: the session reached 1000 stored events | Des événements ont été abandonnés à partir d’ici : la session a dépassé 1000 événements (les événements input et traffic ont leurs propres quotas), ou son serveur n’a pas pu les envoyer à temps. Au plus un par session. |
Les données des événements restent légères : un événement dont le data dépasse 2 KB stocke { "truncated": true } à la place. Les secrets n’apparaissent jamais dans les événements ; lorsqu’une étape en a saisi un, son text affiche {{name}}. De nouveaux types d’événements peuvent être ajoutés : ignorez les types que vous ne connaissez pas plutôt que d’échouer dessus.