Aller au contenu

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: true n’est démarrée que sur l’un d’eux ; si aucun n’est libre, vous obtenez le 503 habituel.

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 :

json
"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.

statusSignification
recordingLa session est en cours et enregistrée.
processingLa session est terminée ; le fichier est en cours de finalisation et d’envoi.
readyVous pouvez le télécharger ou le partager.
failedL’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.
expiredSa 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).

bash
# -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.mp4
python
from 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

Le 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 :

bash
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 :

bash
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) :

bash
curl -H "authorization: Bearer cc_live_..." "https://www.clearcotelabs.com/api/v1/browsers/<id>/events?after=0&limit=200"
json
{
  "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 numérote dans l’ordre les événements d’une session, à partir de 1 ; il peut y avoir des trous. at indique quand l’événement s’est produit.
  • after renvoie les événements qui suivent ce seq (0 par défaut, le début) ; limit va de 1 à 500, 200 par défaut. Les valeurs hors de ces plages renvoient un 400.
  • next est le after de la page suivante, ou null lorsque 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 dernier seq que vous avez vu.
  • Une session conserve au plus 1000 événements, plus jusqu’à 2000 événements input et 1500 traffic ; un unique événement truncated marque 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 input est envoyé une fois l’action terminée : son at (le début de l’action) peut donc précéder celui de l’événement d’avant. Triez par at pour 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"}}, avec at en millisecondes (uniquement les types qu’une vue partagée peut afficher : pas de client.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"]
Cet onglet s’exécute sur votre machine.

Types d’événements

typedataSignification
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 onAvec 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 forUne 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 eventsDes é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.

Mis à jour le 22 nov. 2026 · SDK 0.70.5 · navigateur r63

Cette page vous a-t-elle été utile ?