Pular para o conteúdo

Visualização ao vivo e sessões

Assista a um navegador hospedado ao vivo, assuma o controle ou compartilhe a visualização, gerencie as suas sessões e mantenha um navegador rodando para se reconectar a ele depois.

Toda requisição desta página pode ser enviada a partir da própria página. Com o login feito, os exemplos já levam a sua chave de API e Enviar faz a chamada de verdade e mostra a resposta real, para você alterar um campo e ver o que ele faz.

Um navegador para fazer testes

Quase tudo o que vem a seguir precisa de um navegador em execução. Inicie um aqui: é uma sessão comum, cobrada como qualquer outra (€1.00 por GB do seu saldo), e esta termina sozinha depois de cinco minutos sem nenhum comando, ou de quinze no total.

POST Iniciar um navegador

/api/v1/browsers

A resposta traz o id da sessão e uma connectUrl de uso único. Uma sessão começa quando um cliente se conecta a essa URL (até lá ela fica pending, e expira depois de 45 segundos). Clique em Conectar e a documentação se conecta, lê a aba e desconecta, como o seu script Playwright ou Puppeteer faria; com keepAlive, o navegador continua rodando para as requisições abaixo.

Exemplos
curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers' \
  -H "authorization: Bearer cc_live_..." \
  -H "content-type: application/json" \
  -d '{"keepAlive":true,"url":"https://example.com","idleTimeoutSec":300,"timeoutSec":900,"note":"docs"}'

Visualização ao vivo: assistir, assumir o controle, compartilhar

No painel, clique numa sessão para ver para quais sites foi o tráfego dela e para assistir ao vivo. Clique em Take control para clicar, digitar, rolar, colar e navegar nela você mesmo, por exemplo para fazer login ou passar por uma verificação que o seu script não consegue. O seu script continua conectado o tempo todo, então pause-o enquanto você age. Input humano conta como atividade, então uma sessão que você está controlando não é fechada por inatividade. Share gera um link que qualquer pessoa pode abrir sem conta, só para assistir ou com controle, por 15 minutos a 4 horas e nunca além do fim da sessão. Um link Watch + replay mostra a sessão ao vivo e, quando ela termina, o seu replay: cada clique, rolagem e página desenhados sobre a gravação, por até 14 dias.

Pela API:

GET Abrir a visualização ao vivo

/api/v1/browsers/{id}/live

Um WebSocket de visualização ao vivo para uma sessão em execução (abra-o em até 60 s). As mensagens binárias são frames JPEG; as de texto são {"url","title","tabs"}. Com control=1, a resposta traz "interactive": true quando o controle foi concedido. Assistir aqui abre a visualização nesta página. Cada evento da linha do tempo também chega assim que acontece, como {"ev": …} (veja Gravações).

Exemplos
curl 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/live' \
  -H "authorization: Bearer cc_live_..."

POST Compartilhar a visualização ao vivo

/api/v1/browsers/{id}/share

Um link que qualquer pessoa pode abrir sem conta: controle opcional, de 1 a 240 minutos (padrão 30), nunca além do fim da sessão. Trate um link com controle como a sua chave de API. Com replay: true (e sem controle) ele passa a ser um link de assistir + replay: ao vivo enquanto a sessão roda e, depois, o seu replay, de 1 a 20160 minutos (padrão 10080, 7 dias).

Exemplos
curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/share' \
  -H "authorization: Bearer cc_live_..." \
  -H "content-type: application/json" \
  -d '{"control":false,"minutes":60}'

Com controle, envie mensagens de texto JSON pelo mesmo WebSocket. As coordenadas são frações (de 0 a 1) do frame que você está vendo; qualquer outra coisa é ignorada.

MensagemO que faz
{"t":"mouse","e":"down","x":0.5,"y":0.3,"b":"left","n":1,"m":0}Pressiona (down), solta (up) ou move; n é o número de cliques e m, os modificadores (Alt 1, Ctrl 2, Meta 4, Shift 8).
{"t":"wheel","x":0.5,"y":0.5,"dx":0,"dy":400}Rola uma quantidade de pixels num ponto.
{"t":"key","e":"down","key":"a","code":"KeyA","kc":65,"text":"a"}Uma tecla sendo pressionada ou solta, do jeito que um teclado envia.
{"t":"text","text":"pasted text"}Insere texto como se tivesse sido digitado (até 5000 caracteres).
{"t":"nav","a":"back"}, forward, reload ou {"t":"nav","a":"go","url":"example.com"}Histórico, recarregar ou abrir um endereço http(s).

GET /api/v1/browsers/<id> inclui traffic: os 20 sites com mais bytes naquela sessão.

Gerenciando sessões

GET Uma sessão

/api/v1/browsers/{id}

O status, o tráfego, os segundos e o custo dela até agora. Os campos estão descritos abaixo das requisições.

curl 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \
  -H "authorization: Bearer cc_live_..."

GET As suas sessões

/api/v1/browsers

O seu saldo e as suas sessões, das mais recentes para as mais antigas: 20 por padrão, até 100 com limit. Filtre por status e pelo texto da nota; volte páginas passando em before o createdAt da última sessão que você recebeu. Clique em Usar numa linha para trabalhar com essa sessão nas outras requisições.

Exemplos
curl 'https://www.clearcotelabs.com/api/v1/browsers' \
  -H "authorization: Bearer cc_live_..."

PATCH Rotular uma sessão

/api/v1/browsers/{id}

Defina ou altere a note (no máximo 256 caracteres); null a apaga.

Exemplos
curl -X PATCH 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \
  -H "authorization: Bearer cc_live_..." \
  -H "content-type: application/json" \
  -d '{"note":"shop-de nightly"}'

DELETE Parar uma sessão

/api/v1/browsers/{id}

Uma sessão à qual ninguém se conectou termina na hora; um navegador em execução é fechado pelo servidor dele dentro de um intervalo de relatório, cerca de 15 segundos.

curl -X DELETE 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \
  -H "authorization: Bearer cc_live_..."

Dê uma note à sessão ao criá-la para encontrá-la de novo na lista e no painel. Para iniciar uma sessão no mesmo servidor de uma anterior (caches aquecidos, a mesma máquina), passe o worker daquela sessão; quando esse servidor estiver cheio ou offline, a sessão inicia em outro servidor e os warnings dela avisam.

Uma sessão também termina quando você fecha o navegador ou desconecta, e quando um dos limites abaixo é atingido. Um pedido de parada encerra na hora uma sessão à qual ninguém se conectou; um navegador em execução é fechado pelo servidor dele dentro de um intervalo de relatório, cerca de 15 segundos. O GET responde com:

json
{
  "id": "bs_…",
  "status": "active",                 // see the table below
  "proxy": "managed",                 // or "custom"
  "createdAt": "…", "startedAt": "…", "endedAt": null,
  "endReason": null,                  // set once ended, e.g. "user", "balance", "launch_failed"
  "stopRequested": false,
  "usage": { "bytesUp": 120334, "bytesDown": 4812009, "gb": 0.0049, "seconds": 41 },
  "traffic": [ { "site": "example.com", "bytesUp": 20400, "bytesDown": 3100000 }, … ], // top 20 sites
  "costEur": 0.0050,
  "pricing": { "eurPerGb": 1, "eurPerHour": 0 },
  "queue": { "state": null, "position": null, "ahead": null, "etaSec": null, "updatedAt": "…" } // see below
}
statusSignificado
pendingCreated; nobody has connected yet. Counts towards the concurrency limit until it starts or expires (45 seconds after it was created; a run waits for its server instead).
activeA browser is running and reporting usage.
lostNo usage report for 5 minutes. Billed up to the last report; a late report puts it back to active. If none comes, it ends an hour after the longest a session may last (see Limits and errors): status ended, endReason worker_silent. If the server that ran it restarted, it ends as soon as that server is back: endReason worker_restarted, billed up to the last report.
endedClosed: you disconnected, stopped it, or a limit or the balance ended it. endReason says which. A launch its geo identity refused (geoIdentity strict) ends with endReason geo_refused:<code>, e.g. geo_refused:GEO_PROXY_COUNTRY_TIMEZONE_MISMATCH, and is not billed.
expiredNobody connected before expiresAt (45 seconds after creating it). Never billed.

queue diz em que posição um navegador que está iniciando se encontra na fila de inicialização do seu servidor, para que um momento de pico apareça como um lugar na fila, e não como uma conexão lenta. A resposta de criação também traz uma estimativa: "queue": { "position": 3, "etaSec": 6 }, onde o navegador entraria se você se conectasse agora (ambos null quando o servidor não informa nenhuma fila).

campo de queueSignificado
statewaiting_for_client: created, nobody has connected yet. queued: you connected and the browser waits for a launch slot on its server. launching: it is starting now. null: running, ended, or the server reported no queue in the last 30 seconds.
position1-based place in the server's waiting list while queued, else null.
aheadHow many browsers start before this one: position - 1 while queued, 0 while launching, else null.
etaSecEstimated seconds until it starts while queued: the browsers ahead, launched as many at a time as the server allows, at its average launch time. Else null.
updatedAtWhen the server last reported its queue (ISO time), or null when it has not in the last 30 seconds.

A chamada de listagem, GET /api/v1/browsers, retorna { balanceEur, sessions: [...] } com os mesmos objetos de sessão, dos mais recentes para os mais antigos.

Mantendo o navegador aberto e reconectando

Por padrão, uma sessão termina quando o seu cliente desconecta. Inicie-a com keepAlive: true e o navegador continua rodando, com as abas, os cookies e o IP de saída, para que um script posterior (ou o mesmo, depois de um crash ou de fechar o notebook) continue de onde o anterior parou:

POST Reconectar

/api/v1/browsers/{id}/connect

Uma nova URL de conexão de uso único para uma sessão keepAlive em execução (conecte-se em até 45 segundos). Conectar retoma o navegador a partir desta página, com abas e tudo.

curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/connect' \
  -H "authorization: Bearer cc_live_..."
  • Deixe-o rodando desconectando: browser.close() do Playwright (via connectOverCDP ele só desconecta), browser.disconnect() do Puppeteer ou simplesmente encerrando o seu processo.
  • Encerre-o com DELETE /api/v1/browsers/<id> ou enviando o comando CDP Browser.close: o browser.close() do Puppeteer faz isso e, no Playwright, await (await browser.newBrowserCDPSession()).send("Browser.close"). Até lá, ele continua ocupando uma vaga no seu limite de concorrência.
  • Um cliente por vez: uma reconexão enquanto outro cliente está conectado é recusada com 409, assim como uma reconexão a uma sessão iniciada sem keepAlive.
  • Os limites continuam valendo enquanto ninguém está conectado: idleTimeoutSec (aumente, até 1800, para um navegador ao qual você pretende voltar), timeoutSec, maxGb e o seu saldo. Uma página deixada aberta continua carregando tráfego em segundo plano, que é cobrado como qualquer outro.