Gravações e a linha do tempo de eventos
Duas formas de ver depois o que um navegador hospedado fez. Uma gravação é um vídeo da tela do navegador. A linha do tempo de eventos é uma lista do que aconteceu, com horários: páginas, abas, cliques, rolagens e digitação, o que os solvers de desafios decidiram, passos do agente, transferências e limites. O replay junta os dois: o vídeo com cada ação desenhada por cima. Tudo isso funciona para sessões que você controla e para execuções de agente.
Gravar uma sessão
Passe record: true ao criar a sessão ou a execução. A gravação fica desativada por padrão.
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}'- O vídeo mostra a aba ativa, como a visualização ao vivo, a poucos quadros por segundo, num MP4 H.264 de 1280×800 (outros tamanhos de janela ganham faixas pretas). Ele serve para ver o que aconteceu, não para uma reprodução fluida.
- A gravação para quando a sessão termina ou quando o arquivo atinge um limite de tamanho; a sessão em si continua.
- Ela não é cobrada como tráfego: os quadros são capturados no nosso servidor, não baixados da internet.
- Só alguns servidores conseguem gravar. Uma sessão com
record: truesó é iniciada em um que consiga; se nenhum estiver livre, você recebe o503de sempre.
Status
A visão da sessão (GET /api/v1/browsers/<id>, e a session de uma execução) tem um campo recording: null quando a sessão não foi gravada; caso contrário:
"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 e expiresAt são null até a gravação ficar ready.
| status | Significado |
|---|---|
recording | A sessão está rodando e sendo gravada. |
processing | A sessão terminou; o arquivo está sendo finalizado e enviado. |
ready | Você pode baixá-la ou compartilhá-la. |
failed | Não foi possível fazer ou enviar a gravação: a sessão nunca começou, o servidor não conseguiu finalizar o arquivo ou ele ainda não tinha chegado 25 horas depois do fim da sessão. Não há arquivo. |
expired | Passou do período de retenção: o arquivo foi excluído. |
O arquivo é enviado depois que a sessão termina, então uma gravação fica ready um pouco depois da sessão; uma longa demora mais. Se 25 horas depois do fim da sessão ela ainda não tiver chegado, é marcada como failed. Para ser avisado em vez de consultar repetidamente, adicione um webhook recording.ready.
Download
GET /api/v1/browsers/<id>/recording responde com um redirecionamento 302 para um link de download privado que funciona por no máximo 5 minutos. Siga-o imediatamente em vez de guardá-lo. Enquanto a gravação está em recording ou processing, a resposta é 409 com o código NOT_READY; uma sessão que não foi gravada, cuja gravação falhou ou expirou dá 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 linkO painel reproduz a gravação ao lado dos detalhes da sessão, como um replay.
O replay
Um replay reproduz a gravação com a linha do tempo da sessão desenhada por cima: o ponteiro e o caminho dele, um anel onde cada clique caiu, o trajeto de cada arrasto (incluindo um slider que o solver arrastou), cada rolagem e cada sequência de digitação, a página que abriu, o que os solvers de desafios decidiram e os passos do agente como legendas. Ao lado, a lista de atividade: clique numa linha para pular até ela, e a linha do momento acompanha o vídeo. Acelere ou pule os trechos em que nada acontece. Uma sessão que não foi gravada também pode ter replay: as ações dela são reproduzidas num palco vazio, em ordem e no ritmo real.
Abaixo da imagem, os números da sessão, no momento que você está assistindo e no total: quanto tempo ela rodou, quanto passou pelo proxy dela (download e upload), as páginas que abriu, os cliques, as rolagens e os caracteres digitados, e como foram os desafios dela. Um gráfico de vazão mostra o tráfego no mesmo relógio do vídeo, com o cursor de reprodução nele; clique no gráfico para pular até aquele ponto. Ao lado, os sites que mais consumiram dados e, abaixo, como a sessão chegou à internet (residencial, o seu próprio proxy ou direto, com o país que ela pediu), as conexões que abriu e quantas falharam, as novas tentativas do proxy e os anúncios e rastreadores que o adblock recusou. Um link compartilhado nunca mostra o endereço do proxy nem quanto a sessão custou; o seu painel acrescenta o custo.
O texto digitado nunca é registrado na linha do tempo, só quantos caracteres foram digitados e os nomes de teclas como Enter ou Tab; o vídeo mostra o que a página mostrou, como explicado abaixo.
Compartilhar uma sessão: ao vivo e depois o replay
Um link de acompanhamento mostra a sessão ao vivo enquanto ela roda, com o que ela faz listado ao lado, e quando ela termina o mesmo link abre o replay dela. Não é preciso ter conta para abri-lo, e ele nunca dá controle:
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 para qualquer uma das suas sessões, em andamento ou encerrada. minutes define por quanto tempo o link funciona: de 1 a 20160 (14 dias), padrão 10080 (7 dias). control não se aplica (400). O replay reproduz a gravação quando a sessão foi gravada (record: true), e as ações num palco vazio quando não foi. O token fica depois do #, então nunca chega a um log de servidor, e ele permanece no endereço da página, de modo que o endereço pode ser repassado como está. Qualquer pessoa com o link pode assistir à sessão e ao replay dela até ele expirar, então compartilhe-o só com quem pode vê-la. A linha do tempo exibida traz os endereços das páginas sem a query string. No painel, Share na visualização ao vivo gera o mesmo link (Watch + replay), e uma sessão encerrada tem Share replay.
Compartilhar uma gravação
Para mostrar só o vídeo a alguém sem conta, crie um link de gravação. Ele abre uma página deste site que reproduz o vídeo, até o link expirar:
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": "…" }É a mesma chamada share usada para um link de visualização ao vivo, com recording: true; minutes define por quanto tempo o link funciona: de 1 a 240, padrão 30, e nunca além do expiresAt da gravação. Uma gravação que ainda não está pronta responde 409 NOT_READY, e control não se aplica (400). O token fica depois do #, então nunca chega a um log de servidor; repasse o link inteiro. Os tipos de link são mantidos separados: um link de gravação não abre uma visualização ao vivo, e um link de visualização ao vivo não abre um replay (um link de acompanhamento abre os dois). Qualquer pessoa com um link de gravação pode assistir ao vídeo, então trate-o como a própria gravação.
Retenção e privacidade
- As gravações ficam armazenadas de forma privada por 14 dias a partir de quando ficam
ready. Emrecording.expiresAt, os links de download e de replay param de funcionar e o arquivo é excluído logo depois; baixe antes disso o que quiser guardar. - Links de download são entregues só a você (pela sua chave de API ou pelo painel) e param de funcionar em no máximo 5 minutos; até lá, qualquer pessoa que tenha um pode usá-lo.
- Uma gravação mostra o que a página mostrou. Tudo o que é digitado num campo comum aparece no vídeo, inclusive um segredo digitado num campo que exibe o texto. Campos de senha mostram pontos, como na tela. Deixe a gravação desativada nas execuções cujas telas você não quer que sejam armazenadas.
A linha do tempo de eventos
Toda sessão mantém uma linha do tempo. Leia-a com GET /api/v1/browsers/<id>/events, que também funciona para execuções (o id de uma execução é o id da sessão dela):
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
}seqnumera os eventos de uma sessão em ordem, a partir de 1; pode haver lacunas.até quando o evento aconteceu.afterretorna os eventos depois desseseq(padrão 0, o início);limitvai de 1 a 500, padrão 200. Valores fora dessas faixas dão400.nexté oafterda página seguinte, ounullquando você já tem tudo o que foi armazenado até agora.- Enquanto uma sessão roda, os eventos dela chegam em lotes junto com os relatórios de uso do navegador, mais ou menos a cada 15 segundos. Para acompanhar uma sessão ao vivo, continue consultando com
afterigual ao últimoseqque você viu. - Uma sessão guarda no máximo 1000 eventos e, além deles, até 2000 eventos
inpute 1500traffic; um único eventotruncatedmarca onde eventos foram descartados. Os eventos são excluídos 2 dias depois do fim da sessão. - Um evento
inputé enviado depois que a ação termina, então oatdele (quando a ação começou) pode ser anterior ao do evento anterior. Ordene poratpara mostrar a ordem em que as coisas aconteceram. - Uma visualização ao vivo recebe os eventos à medida que acontecem, sem esperar um relatório de uso: cada um chega pelo WebSocket dela como uma mensagem de texto
{"ev": {"seq", "at", "type", "data"}}, comatem milissegundos (só os tipos que uma visualização compartilhada pode mostrar: semclient.connected, comandos ou hosts recusados, detalhes do perfil ou custos).
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"]Tipos de evento
| type | data | Significado |
|---|---|---|
session.started | { kind, proxy, country?, state?, city?, adblock, headless, geo? } | O navegador está pronto. kind é "cdp" para uma sessão que você controla e "run" para uma execução de agente. |
navigation | { url, title } | Uma aba foi para um novo endereço. No máximo um por segundo por aba. |
tab.opened | { url } | Uma nova aba ou pop-up foi aberta. |
tab.closed | {} | Uma aba foi fechada. |
cdp.denied | { method, reason } | O navegador hospedado recusou um comando CDP, por exemplo um upload de arquivo a partir do servidor. No máximo 50 por sessão. |
profile.loaded | { cookies, files } | Um perfil salvo foi carregado no navegador. |
profile.saved | { cookies, bytes } | O perfil foi salvo de volta no fim da sessão. |
run.started | { jet: { version, commit } } | O Jet começou uma execução, e com qual versão. |
run.step | { step, kind, action, text, probability, url } | Um passo de uma execução, como em result.steps. Segredos em text aparecem como {{name}}. |
run.finished | { status, detail } | O Jet parou, com o status do resultado (done, blocked, needs_input, budget, error). |
handoff.requested | { reason } | O agente de uma execução pediu uma pessoa (handoff: true). Uma transferência que você inicia com POST …/handoff não aparece na linha do tempo; para essas, use o webhook handoff.requested. |
handoff.done | {} | A transferência de uma execução foi marcada como concluída (o botão “I'm done”, o painel ou a API) e o agente continuou. |
recording.started | { fps } | O primeiro quadro da gravação: o 0 s do vídeo. A posição de um evento no vídeo é o at dele menos o deste. fps é a taxa de quadros. |
slider | { variant, outcome, attempt?, reason?, site } | Uma tentativa em um desafio de slider (solveSliders). variant é slide ou puzzle; outcome é passed (o desafio sumiu), failed (ele ainda estava lá; attempt conta as tentativas, no máximo três por página) ou skipped, com um reason, quando um quebra-cabeça foi deixado como estava em vez de arrastado num palpite. |
checkbox | { outcome, attempt?, reason?, site } | Uma tentativa em um desafio de caixa de seleção (solveCheckboxes): uma caixa de “verifique que você é humano” foi clicada. outcome é passed (a caixa sumiu ou foi marcada), failed (ela ainda estava esperando; attempt conta as tentativas, no máximo três por página) ou skipped, com um reason. |
pressHold | { outcome, attempt?, reason?, site } | Uma tentativa em um desafio de manter pressionado (solvePressHold): um botão de verificação de manter pressionado foi segurado até indicar que tinha terminado. outcome é passed (o botão indicou que terminou ou sumiu), failed (não indicou; um pressionamento que ficou sem tempo tem o reason timeout, e attempt conta as tentativas) ou skipped, com um reason. |
challenge.detected | { category, solvable, reason?, site } once per challenge per page, with challengeService on | Com challengeService ativado: um desafio que a página mostrou, uma vez por desafio por página. category (token, score, clearance, block-page, image), solvable e um reason quando não for (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 | Um pedido ao serviço de resolução (challengeService). outcome é solved (a resposta foi aplicada e o desafio sumiu; applied diz como: callback, field, cookie, typed, dragged, hook), failed ou skipped, com um reason (unsolved, still_there, bad_key, no_balance, budget, ...). costUsd é o que o serviço cobrou por ele. |
client.connected | { ip, ua } | Um cliente CDP se conectou à sessão (também numa reconexão): o endereço que o servidor da sessão viu e o User-Agent do cliente. |
egress.refused | { host, port, reason } | O navegador tentou acessar um endereço privado, de loopback ou link-local (reason: private, loopback, link-local, own-ip, blocked-range) ou uma porta bloqueada como a 25 (blocked-port), e a conexão foi recusada. Uma vez por host e porta, no máximo 50 por sessão. |
input | { kind, by, x?, y?, vw?, vh?, shown?, ms, path?, x2?, y2?, dx?, dy?, button?, n?, chars?, keys? } | Uma ação na página, depois que ela termina: kind é click, drag, tap, scroll, type, move (o ponteiro se moveu e parou sem clicar) ou capped (a partir daqui as ações da sessão deixam de ser guardadas). by diz quem agiu: client (a sua conexão), agent (o agente de uma execução), viewer (uma pessoa na visualização ao vivo) ou solver (os solvers de desafios). x, y são pixels CSS no viewport vw × vh da página; shown é true na aba que a visualização ao vivo e a gravação mostram e false em outra aba. path é o trajeto do ponteiro como [ms from at, x, y], ms quanto tempo a ação levou. type traz chars, quantos caracteres foram digitados, e keys, os nomes de teclas como Enter ou Tab e de atalhos como Ctrl+V; nunca o texto. |
traffic | { up, down, conns, failed, retries, blocked } | O que passou até agora pelo proxy da sessão, acumulado: up e down em bytes, conns conexões abertas, failed conexões que não puderam ser feitas, retries túneis tentados de novo após uma falha momentânea do proxy, blocked requisições recusadas pelo adblock. A cada poucos segundos enquanto algum deles mudar; o replay mostra isso em um gráfico. |
limit | { reason } | Um limite foi atingido: max_duration, idle_timeout, max_bytes, max_files_size (a pasta de arquivos da sessão está cheia) ou max_recording_size (só a gravação parou; a sessão continua). Ficar sem saldo aparece apenas em 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? } | A sessão terminou, e o motivo (o mesmo que o endReason da sessão). |
truncated | {} One marker at the first event that was not kept: the session reached 1000 stored events | Eventos foram descartados a partir daqui: a sessão passou de 1000 eventos (eventos input e traffic têm cotas próprias) ou o servidor dela não conseguiu enviá-los a tempo. No máximo um por sessão. |
Os dados dos eventos são mantidos pequenos: um evento cujo data passa de 2 KB guarda { "truncated": true } no lugar. Segredos nunca aparecem nos eventos; quando um passo digitou um, o text dele mostra {{name}}. Novos tipos de evento podem ser adicionados, então ignore os tipos que você não conhece em vez de falhar por causa deles.