Saltar al contenido

Grabaciones y la línea de tiempo de eventos

Dos formas de ver después qué hizo un navegador alojado. Una grabación es un video de la pantalla del navegador. La línea de tiempo de eventos es una lista de lo que pasó, con marcas de tiempo: páginas, pestañas, clics, desplazamientos y escritura, lo que decidieron los solvers de desafíos, pasos del agente, traspasos y límites. La repetición combina ambas: el video con cada acción dibujada encima. Todo esto funciona para las sesiones que controlas tú y para las ejecuciones de agente.

Grabar una sesión

Pasa record: true al crear la sesión o la ejecución. La grabación está desactivada por defecto.

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}'
  • El video muestra la pestaña activa, como la vista en vivo, a pocos fotogramas por segundo, en un MP4 H.264 de 1280×800 (los demás tamaños de ventana llevan bandas negras). Está pensado para ver qué pasó, no para una reproducción fluida.
  • La grabación se detiene cuando termina la sesión o cuando el archivo alcanza un límite de tamaño; la sesión en sí continúa.
  • No se factura como tráfico: los fotogramas se capturan en nuestro servidor, no se descargan de internet.
  • Solo algunos servidores pueden grabar. Una sesión con record: true solo se inicia en uno que pueda; si no hay ninguno libre, recibes el 503 de siempre.

Estado

La vista de la sesión (GET /api/v1/browsers/<id>, y la session de una ejecución) tiene un campo recording: null cuando la sesión no se grabó; si no:

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 y expiresAt son null hasta que la grabación está ready.

statusSignificado
recordingLa sesión está en curso y se está grabando.
processingLa sesión terminó; el archivo se está terminando de generar y subiendo.
readyPuedes descargarla o compartirla.
failedNo se pudo hacer o subir la grabación: la sesión nunca empezó, el servidor no pudo terminar el archivo o este seguía sin llegar 25 horas después del final de la sesión. No hay archivo.
expiredPasó su periodo de retención: el archivo se eliminó.

El archivo se sube cuando la sesión ya terminó, así que una grabación pasa a ready un poco después que la sesión; una larga tarda más. Si 25 horas después del final de la sesión todavía no llegó, se marca como failed. Para recibir un aviso en lugar de consultar, agrega un webhook recording.ready.

Descargar

GET /api/v1/browsers/<id>/recording responde con una redirección 302 a un enlace de descarga privado que funciona durante 5 minutos como máximo. Síguelo de inmediato en lugar de guardarlo. Mientras la grabación está en recording o processing, la respuesta es 409 con el código NOT_READY; una sesión que no se grabó, cuya grabación falló o cuya grabación expiró da 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

El panel reproduce la grabación junto a los detalles de la sesión, como una repetición.

La repetición

Una repetición reproduce la grabación con la línea de tiempo de la sesión dibujada encima: el puntero y su recorrido, un anillo donde cayó cada clic, el trayecto de cada arrastre (incluido un deslizador que arrastró el solver), cada desplazamiento y cada ráfaga de escritura, la página que se abrió, lo que decidieron los solvers de desafíos y los pasos del agente como subtítulos. Al lado, la lista de actividad: haz clic en una fila para saltar a ese punto, y la fila del momento sigue al video. Acelérala o sáltate los tramos en los que no pasa nada. Una sesión que no se grabó también se puede repetir: sus acciones se reproducen entonces sobre un escenario vacío, en orden y a su ritmo real.

Debajo de la imagen, las cifras de la sesión, en el momento que estás viendo y en total: cuánto tiempo lleva en ejecución, cuánto pasó por su proxy (bajada y subida), las páginas que abrió, los clics, desplazamientos y caracteres escritos, y cómo le fue con sus desafíos. Un gráfico de rendimiento muestra el tráfico en el mismo reloj que el video, con el cabezal de reproducción encima; haz clic en el gráfico para saltar a ese punto. Al lado, los sitios que consumieron más datos, y debajo, cómo llegó la sesión a internet (residencial, tu propio proxy o directo, con el país que pidió), las conexiones que abrió y cuántas fallaron, los reintentos del proxy y los anuncios y rastreadores que rechazó adblock. Un enlace compartido nunca muestra la dirección del proxy ni lo que costó la sesión; tu panel agrega el costo.

El texto escrito nunca se guarda en la línea de tiempo, solo cuántos caracteres se escribieron y los nombres de teclas como Enter o Tab; el video muestra lo que mostró la página, como se explica más abajo.

Compartir una sesión: en vivo y luego su repetición

Un enlace de visualización muestra la sesión en vivo mientras se ejecuta, con lo que hace listado al lado, y cuando termina, el mismo enlace abre su repetición. No hace falta una cuenta para abrirlo, y nunca permite el control:

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 funciona con cualquiera de tus sesiones, en curso o terminada. minutes define cuánto tiempo funciona el enlace: de 1 a 20160 (14 días), por defecto 10080 (7 días). control no aplica (400). La repetición reproduce la grabación cuando la sesión se grabó (record: true), y las acciones sobre un escenario vacío cuando no. El token va después del #, así que nunca llega a un log del servidor, y se queda en la dirección de la página, de modo que la dirección se puede pasar tal cual. Cualquiera que tenga el enlace puede ver la sesión y su repetición hasta que expire, así que compártelo solo con personas que puedan verla. La línea de tiempo que muestra da las direcciones de las páginas sin su query string. En el panel, “Share” en la vista en vivo genera el mismo enlace (“Watch + replay”), y una sesión terminada tiene “Share replay”.

Compartir una grabación

Para mostrar solo el video a alguien sin cuenta, crea un enlace de grabación. Abre una página de este sitio que la reproduce, hasta que el enlace expira:

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": "…" }

Es la misma llamada share que para un enlace de vista en vivo, con recording: true; minutes define cuánto tiempo funciona el enlace: de 1 a 240, por defecto 30, y nunca más allá del expiresAt de la grabación. Una grabación que todavía no está lista responde 409 NOT_READY, y control no aplica (400). El token va después del #, así que nunca llega a un log del servidor; pasa el enlace completo. Los tipos de enlace se mantienen separados: un enlace de grabación no puede abrir una vista en vivo, y un enlace de vista en vivo no puede abrir una repetición (un enlace de visualización abre ambas). Cualquiera que tenga un enlace de grabación puede ver el video, así que trátalo como la grabación misma.

Retención y privacidad

  • Las grabaciones se guardan de forma privada durante 14 días desde que pasan a ready. En recording.expiresAt, los enlaces de descarga y de repetición dejan de funcionar y el archivo se elimina poco después; descarga lo que quieras conservar antes de esa fecha.
  • Los enlaces de descarga solo se te dan a ti (con tu clave de API o en el panel) y dejan de funcionar a los 5 minutos como máximo; hasta entonces, cualquiera que tenga uno puede usarlo.
  • Una grabación muestra lo que mostró la página. Todo lo que se escribe en un campo normal aparece en el video, incluido un secreto escrito en un campo que muestra su texto. Los campos de contraseña muestran puntos, como en pantalla. Deja la grabación desactivada en las ejecuciones cuyas pantallas no quieras que se guarden.

La línea de tiempo de eventos

Cada sesión guarda una línea de tiempo. Léela con GET /api/v1/browsers/<id>/events, que también funciona para las ejecuciones (el id de una ejecución es el id de su sesión):

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 numera en orden los eventos de una sesión, desde 1; puede haber huecos. at es cuándo ocurrió.
  • after devuelve los eventos posteriores a ese seq (por defecto 0, el inicio); limit va de 1 a 500, por defecto 200. Los valores fuera de esos rangos dan 400.
  • next es el after para la página siguiente, o null cuando ya tienes todo lo guardado hasta ahora.
  • Mientras una sesión se ejecuta, sus eventos llegan en lotes con los informes de uso del navegador, más o menos cada 15 segundos. Para seguir una sesión en vivo, sigue consultando con after igual al último seq que viste.
  • Una sesión guarda como máximo 1000 eventos y, además, hasta 2000 eventos input y 1500 traffic; un único evento truncated marca dónde se descartaron eventos. Los eventos se eliminan 2 días después de que termina la sesión.
  • Un evento input se envía cuando la acción ya terminó, así que su at (cuándo empezó la acción) puede ser anterior al del evento previo. Ordena por at para mostrar el orden en que ocurrieron las cosas.
  • Una vista en vivo recibe los eventos a medida que ocurren, sin esperar a un informe de uso: cada uno llega por su WebSocket como un mensaje de texto {"ev": {"seq", "at", "type", "data"}}, con at en milisegundos (solo los tipos que puede mostrar una vista compartida: sin client.connected, comandos o hosts rechazados, detalles del perfil ni costos).
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"]
Esta pestaña se ejecuta en tu máquina.

Tipos de eventos

typedataSignificado
session.started{ kind, proxy, country?, state?, city?, adblock, headless, geo? }El navegador está listo. kind es "cdp" para una sesión que controlas tú y "run" para una ejecución de agente.
navigation{ url, title }Una pestaña fue a una nueva dirección. Como máximo uno por segundo por pestaña.
tab.opened{ url }Se abrió una nueva pestaña o ventana emergente.
tab.closed{}Se cerró una pestaña.
cdp.denied{ method, reason }El navegador alojado rechazó un comando CDP, por ejemplo una subida de archivo desde el servidor. Como máximo 50 por sesión.
profile.loaded{ cookies, files }Se cargó un perfil guardado en el navegador.
profile.saved{ cookies, bytes }El perfil se volvió a guardar al final de la sesión.
run.started{ jet: { version, commit } }Jet empezó una ejecución, y con qué versión.
run.step{ step, kind, action, text, probability, url }Un paso de una ejecución, como en result.steps. Los secretos en text aparecen como {{name}}.
run.finished{ status, detail }Jet se detuvo, con el estado del resultado (done, blocked, needs_input, budget, error).
handoff.requested{ reason }El agente de una ejecución pidió una persona (handoff: true). Un traspaso que inicias tú con POST …/handoff no aparece en la línea de tiempo; para esos usa el webhook handoff.requested.
handoff.done{}El traspaso de una ejecución se marcó como terminado (el botón “I'm done”, el panel o la API) y el agente continuó.
recording.started{ fps }El primer fotograma de la grabación: el segundo 0 del video. La posición de un evento en el video es su at menos el de este. fps es la tasa de fotogramas.
slider{ variant, outcome, attempt?, reason?, site }Un intento en un desafío de deslizador (solveSliders). variant es slide o puzzle; outcome es passed (el desafío desapareció), failed (seguía ahí; attempt cuenta los intentos, como máximo tres por página) o skipped, con un reason, cuando un rompecabezas se dejó tal cual en vez de arrastrarlo al azar.
checkbox{ outcome, attempt?, reason?, site }Un intento en un desafío de casilla (solveCheckboxes): se hizo clic en una casilla de “verifica que eres humano”. outcome es passed (la casilla desapareció o quedó marcada), failed (seguía esperando; attempt cuenta los intentos, como máximo tres por página) o skipped, con un reason.
pressHold{ outcome, attempt?, reason?, site }Un intento en un desafío de mantener pulsado (solvePressHold): se mantuvo pulsado un botón de verificación de mantener pulsado hasta que indicó que había terminado. outcome es passed (el botón indicó que había terminado o desapareció), failed (no lo hizo; una pulsación que se quedó sin tiempo tiene el reason timeout, y attempt cuenta los intentos) o skipped, con un reason.
challenge.detected{ category, solvable, reason?, site } once per challenge per page, with challengeService onCon challengeService activado: un desafío que mostró la página, una vez por desafío y por página. category (token, score, clearance, block-page, image), solvable y un reason cuando no lo es (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 forUna solicitud al servicio de resolución (challengeService). outcome es solved (la respuesta se aplicó y el desafío desapareció; applied dice cómo: callback, field, cookie, typed, dragged, hook), failed o skipped, con un reason (unsolved, still_there, bad_key, no_balance, budget, ...). costUsd es lo que cobró el servicio por ella.
client.connected{ ip, ua }Un cliente CDP se conectó a la sesión (también al reconectarse): la dirección que vio el servidor de la sesión y el User-Agent del cliente.
egress.refused{ host, port, reason }El navegador intentó llegar a una dirección privada, de loopback o link-local (reason: private, loopback, link-local, own-ip, blocked-range) o a un puerto bloqueado como el 25 (blocked-port), y la conexión se rechazó. Una vez por host y puerto, como máximo 50 por sesión.
input{ kind, by, x?, y?, vw?, vh?, shown?, ms, path?, x2?, y2?, dx?, dy?, button?, n?, chars?, keys? }Una acción en la página, una vez terminada: kind es click, drag, tap, scroll, type, move (el puntero se movió y se detuvo sin hacer clic) o capped (a partir de aquí ya no se guardan las acciones de la sesión). by indica quién actuó: client (tu conexión), agent (el agente de una ejecución), viewer (una persona en la vista en vivo) o solver (los solvers de desafíos). x, y son píxeles CSS en el viewport vw × vh de la página; shown es true en la pestaña que muestran la vista en vivo y la grabación, y false en otra pestaña. path es el recorrido del puntero como [ms from at, x, y], ms cuánto duró la acción. type da chars, cuántos caracteres se escribieron, y keys, los nombres de teclas como Enter o Tab y de atajos como Ctrl+V; nunca el texto.
traffic{ up, down, conns, failed, retries, blocked }Lo que pasó hasta ahora por el proxy de la sesión, acumulado: up y down en bytes, conns conexiones abiertas, failed conexiones que no se pudieron establecer, retries túneles reintentados tras un fallo momentáneo del proxy, blocked solicitudes rechazadas por adblock. Cada pocos segundos mientras alguno de ellos cambie; la repetición lo muestra en un gráfico.
limit{ reason }Se alcanzó un límite: max_duration, idle_timeout, max_bytes, max_files_size (la carpeta de archivos de la sesión está llena) o max_recording_size (solo se detuvo la grabación; la sesión continúa). Quedarse sin saldo solo aparece en 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 sesión terminó, y por qué (lo mismo que el endReason de la sesión).
truncated{} One marker at the first event that was not kept: the session reached 1000 stored eventsA partir de aquí se descartaron eventos: la sesión superó los 1000 eventos (los eventos input y traffic tienen sus propios cupos) o su servidor no pudo enviarlos a tiempo. Como máximo uno por sesión.

Los datos de los eventos se mantienen pequeños: un evento cuyo data supera los 2 KB guarda { "truncated": true } en su lugar. Los secretos nunca aparecen en los eventos; cuando un paso escribió uno, su text muestra {{name}}. Pueden añadirse nuevos tipos de eventos, así que omite los tipos que no conozcas en lugar de fallar con ellos.

Actualizado el 22 nov 2026 · SDK 0.70.5 · navegador r63

¿Te resultó útil esta página?