Aller au contenu

Vue en direct et sessions

Suivez un navigateur hébergé en direct, prenez la main ou partagez la vue, gérez vos sessions et gardez un navigateur ouvert pour vous y reconnecter plus tard.

Chaque requête de cette page peut être envoyée depuis la page elle-même. Une fois que vous êtes connecté, les exemples contiennent votre clé API, et Envoyer effectue l’appel réel et affiche la vraie réponse : vous pouvez ainsi modifier un champ et voir ce qu’il change.

Un navigateur pour faire des essais

L’essentiel de ce qui suit nécessite un navigateur en cours d’exécution. Démarrez-en un ici : c’est une session ordinaire, facturée comme n’importe quelle autre (€1.00 par Go, prélevés sur votre solde), et celle-ci se termine d’elle-même après cinq minutes sans commande, ou quinze au total.

POST Démarrer un navigateur

/api/v1/browsers

La réponse contient l’id de la session et un connectUrl à usage unique. Une session démarre quand un client se connecte à cette URL (d’ici là, elle est pending, et elle expire au bout de 45 secondes). Appuyez sur Se connecter : la documentation se connecte, lit l’onglet et se déconnecte, comme le ferait votre script Playwright ou Puppeteer ; avec keepAlive, le navigateur continue de tourner pour les requêtes ci-dessous.

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

Vue en direct : regarder, prendre la main, partager

Dans le tableau de bord, cliquez sur une session pour voir vers quels sites est allé son trafic et pour la suivre en direct. Appuyez sur « Take control » pour cliquer, saisir du texte, faire défiler, coller et naviguer vous-même, par exemple pour vous connecter ou franchir une vérification que votre script ne sait pas franchir. Votre script reste connecté pendant tout ce temps : mettez-le en pause pendant que vous intervenez. Les saisies humaines comptent comme de l’activité : une session que vous pilotez n’est donc pas fermée pour inactivité. « Share » crée un lien que n’importe qui peut ouvrir sans compte, en lecture seule ou avec le contrôle, pour une durée de 15 minutes à 4 heures et jamais au-delà de la fin de la session. Un lien « Watch + replay » montre la session en direct puis, une fois terminée, sa relecture : chaque clic, défilement et page dessinés par-dessus l’enregistrement, jusqu’à 14 jours.

Via l’API :

GET Ouvrir la vue en direct

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

Un WebSocket de vue en direct pour une session en cours (à ouvrir dans les 60 s). Les messages binaires sont des images JPEG, les messages texte sont de la forme {"url","title","tabs"}. Avec control=1, la réponse indique "interactive": true si le contrôle a été accordé. Regarder ici ouvre la vue sur cette page. Chaque événement de la chronologie arrive aussi dès qu’il se produit, sous la forme {"ev": …} (voir Enregistrements).

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

POST Partager la vue en direct

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

Un lien que n’importe qui peut ouvrir sans compte : contrôle facultatif, de 1 à 240 minutes (30 par défaut), jamais au-delà de la fin de la session. Traitez un lien avec contrôle comme votre clé API. Avec replay: true (et sans contrôle), c’est un lien de visionnage et de relecture : en direct tant que la session tourne, puis sa relecture, de 1 à 20160 minutes (10080 par défaut, 7 jours).

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

Avec le contrôle, envoyez des messages texte JSON sur le même WebSocket. Les coordonnées sont des fractions (de 0 à 1) de l’image que vous regardez ; tout le reste est ignoré.

MessageEffet
{"t":"mouse","e":"down","x":0.5,"y":0.3,"b":"left","n":1,"m":0}Appui (down), relâchement (up) ou move ; n est le nombre de clics, m les modificateurs (Alt 1, Ctrl 2, Meta 4, Shift 8).
{"t":"wheel","x":0.5,"y":0.5,"dx":0,"dy":400}Défilement d’un nombre de pixels à un point donné.
{"t":"key","e":"down","key":"a","code":"KeyA","kc":65,"text":"a"}Une touche enfoncée ou relâchée, telle qu’un clavier l’envoie.
{"t":"text","text":"pasted text"}Insère du texte comme s’il avait été tapé (jusqu’à 5000 caractères).
{"t":"nav","a":"back"}, forward, reload ou {"t":"nav","a":"go","url":"example.com"}Historique, rechargement ou ouverture d’une adresse http(s).

GET /api/v1/browsers/<id> inclut traffic : les 20 sites qui ont consommé le plus d’octets pendant cette session.

Gérer les sessions

GET Une session

/api/v1/browsers/{id}

Son statut, son trafic, ses secondes et son coût jusqu’à présent. Les champs sont décrits sous les requêtes.

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

GET Vos sessions

/api/v1/browsers

Votre solde et vos sessions, de la plus récente à la plus ancienne : 20 par défaut, jusqu’à 100 avec limit. Filtrez par statut et par texte de note ; pour remonter page par page, donnez à before le createdAt de la dernière session reçue. Sur une ligne, appuyez sur Utiliser pour travailler avec cette session dans les autres requêtes.

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

PATCH Annoter une session

/api/v1/browsers/{id}

Définissez ou modifiez la note (256 caractères au plus) ; null l’efface.

Exemples
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 Arrêter une session

/api/v1/browsers/{id}

Une session à laquelle personne ne s’est connecté se termine immédiatement ; un navigateur en cours d’exécution est fermé par son serveur dans l’intervalle de remontée suivant, soit environ 15 secondes.

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

Donnez une note à une session dès sa création pour la retrouver dans la liste et dans le tableau de bord. Pour démarrer une session sur le même serveur qu’une session précédente (caches déjà chauds, même machine), passez le worker de cette session ; si ce serveur est plein ou hors ligne, la session démarre sur un autre serveur et ses warnings le signalent.

Une session se termine aussi quand vous fermez le navigateur ou vous déconnectez, et quand l’une des limites ci-dessous est atteinte. Une demande d’arrêt met fin immédiatement à une session à laquelle personne ne s’est connecté ; un navigateur en cours d’exécution est fermé par son serveur dans l’intervalle de remontée suivant, soit environ 15 secondes. GET répond avec :

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
}
statusSignification
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 indique où en est un navigateur qui démarre dans la file de lancement de son serveur : un moment chargé se lit ainsi comme une place dans la file plutôt que comme une connexion lente. La réponse de création contient aussi une estimation : "queue": { "position": 3, "etaSec": 6 }, la place que prendrait le navigateur si vous vous connectiez maintenant (les deux à null quand le serveur ne signale aucune file).

Champ de queueSignification
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.

L’appel de liste, GET /api/v1/browsers, renvoie { balanceEur, sessions: [...] } avec les mêmes objets de session, du plus récent au plus ancien.

Garder un navigateur ouvert et s’y reconnecter

Par défaut, une session se termine quand votre client se déconnecte. Démarrez-la avec keepAlive: true et le navigateur continue au contraire de tourner, avec ses onglets, ses cookies et son IP de sortie : un script ultérieur (ou le même, après un plantage ou un portable refermé) peut reprendre là où le précédent s’était arrêté :

POST Se reconnecter

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

Une nouvelle URL de connexion à usage unique pour une session keepAlive en cours (connectez-vous dans les 45 secondes). Se connecter reprend le navigateur depuis cette page, onglets compris.

curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/connect' \
  -H "authorization: Bearer cc_live_..."
  • Laissez-le tourner en vous déconnectant : browser.close() de Playwright (via connectOverCDP, il ne fait que se déconnecter), browser.disconnect() de Puppeteer, ou tout simplement la fin de votre processus.
  • Arrêtez-le avec DELETE /api/v1/browsers/<id>, ou en envoyant la commande CDP Browser.close : c’est ce que fait browser.close() de Puppeteer, et dans Playwright, await (await browser.newBrowserCDPSession()).send("Browser.close"). D’ici là, il occupe toujours une place dans votre limite de concurrence.
  • Un seul client à la fois : une reconnexion alors qu’un autre client est attaché est refusée avec 409, tout comme une reconnexion à une session démarrée sans keepAlive.
  • Les limites s’appliquent même quand personne n’est connecté : idleTimeoutSec (augmentez-le, jusqu’à 1800, pour un navigateur auquel vous comptez revenir), timeoutSec, maxGb et votre solde. Une page laissée ouverte continue de générer son trafic en arrière-plan, facturé comme n’importe quel autre.