Saltar al contenido

Vista en vivo y sesiones

Observa un navegador alojado en vivo, toma el control o comparte la vista, administra tus sesiones y mantén un navegador en ejecución para reconectarte a él más tarde.

Todas las solicitudes de esta página se pueden enviar desde la propia página. Si ya ingresaste, los ejemplos incluyen tu clave de API y Enviar hace la llamada real y te muestra la respuesta real, así que puedes cambiar un campo y ver qué hace.

Un navegador para hacer pruebas

La mayor parte de lo que sigue requiere un navegador en ejecución. Inicia uno aquí: es una sesión normal, que se factura como cualquier otra (€1.00 por GB, con cargo a tu saldo), y esta termina sola tras cinco minutos sin recibir comandos, o a los quince minutos en total.

POST Iniciar un navegador

/api/v1/browsers

La respuesta contiene el id de la sesión y una connectUrl de un solo uso. Una sesión empieza cuando un cliente se conecta a esa URL (hasta entonces está en pending y expira a los 45 segundos). Pulsa Conectar y la documentación se conecta, lee la pestaña y se desconecta, como lo haría tu script de Playwright o Puppeteer; con keepAlive, el navegador sigue en ejecución para las solicitudes de más abajo.

Ejemplos
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"}'

Vista en vivo: observar, tomar el control, compartir

En el panel, haz clic en una sesión para ver a qué sitios fue su tráfico y para verla en vivo. Pulsa “Take control” para hacer clic, escribir, desplazarte, pegar y navegar tú mismo, por ejemplo para iniciar sesión o superar una verificación que tu script no puede. Tu script sigue conectado todo el tiempo, así que ponlo en pausa mientras actúas. La interacción humana cuenta como actividad, así que una sesión que estás controlando no se cierra por inactividad. “Share” genera un enlace que cualquiera puede abrir sin cuenta, solo para ver o con control, válido de 15 minutos a 4 horas y nunca más allá del final de la sesión. Un enlace “Watch + replay” muestra la sesión en vivo y, cuando termina, su repetición: cada clic, desplazamiento y página dibujados sobre la grabación, durante hasta 14 días.

A través de la API:

GET Abrir la vista en vivo

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

Un WebSocket de vista en vivo para una sesión en ejecución (ábrelo en un plazo de 60 s). Los mensajes binarios son fotogramas JPEG; los de texto son {"url","title","tabs"}. Con control=1, la respuesta indica "interactive": true cuando se concedió el control. Verlo aquí abre la vista en esta página. Además, cada evento de la línea de tiempo llega en cuanto ocurre, como {"ev": …} (ver Grabaciones).

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

POST Compartir la vista en vivo

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

Un enlace que cualquiera puede abrir sin cuenta: control opcional, de 1 a 240 minutos (30 por defecto), nunca más allá del final de la sesión. Trata un enlace con control como si fuera tu clave de API. Con replay: true (y sin control) es en cambio un enlace para ver y repetir: en vivo mientras la sesión se ejecuta y después su repetición, de 1 a 20160 minutos (por defecto 10080, 7 días).

Ejemplos
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}'

Con control, envía mensajes de texto JSON por el mismo WebSocket. Las coordenadas son fracciones (de 0 a 1) del fotograma que estás viendo; todo lo demás se ignora.

MensajeQué hace
{"t":"mouse","e":"down","x":0.5,"y":0.3,"b":"left","n":1,"m":0}Pulsar (down), soltar (up) o mover (move); n es la cantidad de clics y m, los modificadores (Alt 1, Ctrl 2, Meta 4, Shift 8).
{"t":"wheel","x":0.5,"y":0.5,"dx":0,"dy":400}Desplazarse una cantidad de píxeles en un punto.
{"t":"key","e":"down","key":"a","code":"KeyA","kc":65,"text":"a"}Una tecla que se presiona o se suelta, tal como la envía un teclado.
{"t":"text","text":"pasted text"}Insertar texto como si se escribiera (hasta 5000 caracteres).
{"t":"nav","a":"back"}, forward, reload o {"t":"nav","a":"go","url":"example.com"}Historial, recargar o abrir una dirección http(s).

GET /api/v1/browsers/<id> incluye traffic: los 20 sitios principales por bytes de esa sesión.

Administrar sesiones

GET Una sesión

/api/v1/browsers/{id}

Su estado, tráfico, segundos y costo hasta el momento. Los campos se describen debajo de las solicitudes.

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

GET Tus sesiones

/api/v1/browsers

Tu saldo y tus sesiones, de la más reciente a la más antigua: 20 por defecto, hasta 100 con limit. Filtra por estado y por el texto de la nota; para ver las anteriores, usa before con el valor de createdAt de la última sesión que recibiste. Pulsa Usar en una fila para trabajar con esa sesión en las demás solicitudes.

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

PATCH Etiquetar una sesión

/api/v1/browsers/{id}

Define o cambia la note (256 caracteres como máximo); null la borra.

Ejemplos
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 Detener una sesión

/api/v1/browsers/{id}

Una sesión a la que nadie se conectó termina de inmediato; un navegador en ejecución lo cierra su servidor dentro de un intervalo de reporte, unos 15 segundos.

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

Ponle una note a la sesión al crearla para encontrarla después en la lista y en el panel. Para iniciar una sesión en el mismo servidor que una anterior (cachés ya calientes, la misma máquina), pasa el worker de esa sesión; si ese servidor está lleno o desconectado, la sesión arranca en otro servidor y sus warnings lo indican.

Una sesión también termina cuando cierras el navegador o te desconectas, y cuando se alcanza alguno de los límites que se describen más abajo. Una solicitud de detención termina de inmediato una sesión a la que nadie se conectó; un navegador en ejecución lo cierra su servidor dentro de un intervalo de reporte, unos 15 segundos. GET responde con:

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 indica en qué lugar de la cola de arranque de su servidor está un navegador que se está iniciando, así que un momento de mucha carga se lee como un puesto en la fila y no como una conexión lenta. La respuesta de creación también incluye una estimación: "queue": { "position": 3, "etaSec": 6 }, el lugar donde entraría el navegador si te conectaras ahora (ambos null cuando el servidor no reporta ninguna cola).

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.

La llamada de listado, GET /api/v1/browsers, devuelve { balanceEur, sessions: [...] } con los mismos objetos de sesión, de la más reciente a la más antigua.

Mantener un navegador abierto y reconectarse

Por defecto, una sesión termina cuando tu cliente se desconecta. Iníciala con keepAlive: true y el navegador sigue en ejecución, con sus pestañas, cookies e IP de salida, para que un script posterior (o el mismo, después de un fallo o de cerrar la laptop) retome donde se quedó el anterior:

POST Reconectar

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

Una nueva URL de conexión de un solo uso para una sesión keepAlive en ejecución (conéctate en un plazo de 45 segundos). Conectar retoma el navegador desde esta página, con todas sus pestañas.

curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/connect' \
  -H "authorization: Bearer cc_live_..."
  • Para dejarlo en ejecución, desconéctate: con browser.close() de Playwright (sobre connectOverCDP solo desconecta), con browser.disconnect() de Puppeteer o simplemente terminando tu proceso.
  • Para terminarlo, usa DELETE /api/v1/browsers/<id> o envía el comando CDP Browser.close: el browser.close() de Puppeteer lo hace, y en Playwright, await (await browser.newBrowserCDPSession()).send("Browser.close"). Hasta entonces, sigue ocupando su lugar en tu límite de concurrencia.
  • Un cliente a la vez: una reconexión mientras hay otro cliente conectado se rechaza con 409, igual que una para una sesión iniciada sin keepAlive.
  • Los límites siguen aplicándose mientras nadie está conectado: idleTimeoutSec (súbelo, hasta 1800, si piensas volver a ese navegador), timeoutSec, maxGb y tu saldo. Una página que queda abierta sigue cargando su tráfico en segundo plano, que se factura como cualquier otro.