Pular para o conteúdo

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: true só é iniciada em um que consiga; se nenhum estiver livre, você recebe o 503 de 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:

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 e expiresAt são null até a gravação ficar ready.

statusSignificado
recordingA sessão está rodando e sendo gravada.
processingA sessão terminou; o arquivo está sendo finalizado e enviado.
readyVocê pode baixá-la ou compartilhá-la.
failedNã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.
expiredPassou 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).

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

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

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

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

É 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. Em recording.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):

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 os eventos de uma sessão em ordem, a partir de 1; pode haver lacunas. at é quando o evento aconteceu.
  • after retorna os eventos depois desse seq (padrão 0, o início); limit vai de 1 a 500, padrão 200. Valores fora dessas faixas dão 400.
  • next é o after da página seguinte, ou null quando 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 after igual ao último seq que você viu.
  • Uma sessão guarda no máximo 1000 eventos e, além deles, até 2000 eventos input e 1500 traffic; um único evento truncated marca 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 o at dele (quando a ação começou) pode ser anterior ao do evento anterior. Ordene por at para 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"}}, com at em milissegundos (só os tipos que uma visualização compartilhada pode mostrar: sem client.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"]
Esta aba roda na sua máquina.

Tipos de evento

typedataSignificado
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 onCom 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 forUm 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 eventsEventos 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.

Atualizado em 22 de nov. de 2026 · SDK 0.70.5 · navegador r63

Esta página foi útil?