Live-Ansicht und Sessions
Sehen Sie einem gehosteten Browser live zu, übernehmen Sie die Steuerung oder teilen Sie die Ansicht, verwalten Sie Ihre Sessions und lassen Sie einen Browser weiterlaufen, damit Sie sich später wieder mit ihm verbinden können.
Jede Anfrage auf dieser Seite können Sie direkt von hier aus senden. Wenn Sie angemeldet sind, enthalten die Beispiele Ihren API-Schlüssel, und Senden führt den echten Aufruf aus und zeigt Ihnen die echte Antwort. So können Sie ein Feld ändern und sehen, was es bewirkt.
Ein Browser zum Ausprobieren
Für das meiste, was folgt, brauchen Sie einen laufenden Browser. Starten Sie hier einen: Es ist eine gewöhnliche Session, die wie jede andere abgerechnet wird (€1.00 pro GB aus Ihrem Guthaben), und diese hier endet von selbst nach fünf Minuten ohne Befehl oder nach insgesamt fünfzehn Minuten.
POST Browser starten
Die Antwort enthält die id der Session und eine einmalig gültige connectUrl. Eine Session startet, wenn sich ein Client mit dieser URL verbindet (bis dahin ist sie pending, und nach 45 Sekunden verfällt sie). Klicken Sie auf Verbinden, dann verbindet sich die Dokumentation, liest den Tab aus und trennt die Verbindung wieder, so wie es Ihr Playwright- oder Puppeteer-Skript tun würde; mit keepAlive läuft der Browser für die nachfolgenden Anfragen weiter.
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"}'
Live-Ansicht: zusehen, übernehmen, teilen
Klicken Sie im Dashboard auf eine Session, um zu sehen, an welche Sites ihr Traffic ging, und um sie live zu verfolgen. Über Take control können Sie selbst darin klicken, tippen, scrollen, einfügen und navigieren, etwa um sich anzumelden oder eine Prüfung zu bestehen, an der Ihr Skript scheitert. Ihr Skript bleibt die ganze Zeit verbunden; pausieren Sie es also, während Sie eingreifen. Menschliche Eingaben zählen als Aktivität, daher wird eine Session, die Sie gerade steuern, nicht wegen Inaktivität geschlossen. Share erzeugt einen Link, den jeder ohne Account öffnen kann, nur zum Zusehen oder mit Steuerung, für 15 Minuten bis 4 Stunden und nie über das Ende der Session hinaus. Ein Link mit Watch + replay zeigt die Session live und nach ihrem Ende ihre Wiedergabe: jeden Klick, jedes Scrollen und jede Seite über der Aufzeichnung, bis zu 14 Tage lang.
Über die API:
GET Live-Ansicht öffnen
Ein WebSocket für die Live-Ansicht einer laufenden Session (öffnen Sie ihn innerhalb von 60 s). Binäre Nachrichten sind JPEG-Frames, Textnachrichten sind {"url","title","tabs"}. Mit control=1 enthält die Antwort "interactive": true, wenn die Steuerung gewährt wurde. Hier ansehen öffnet die Ansicht auf dieser Seite. Jedes Ereignis der Timeline kommt außerdem sofort an, als {"ev": …} (siehe Aufzeichnungen).
curl 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/live' \ -H "authorization: Bearer cc_live_..."
POST Live-Ansicht teilen
Ein Link, den jeder ohne Account öffnen kann: Steuerung optional, 1 bis 240 Minuten (Standard 30), nie über das Ende der Session hinaus. Behandeln Sie einen Link mit Steuerung wie Ihren API-Schlüssel. Mit replay: true (und ohne Steuerung) ist es stattdessen ein Link zum Zusehen und zur Wiedergabe: live, solange die Session läuft, danach ihre Wiedergabe, 1 bis 20160 Minuten (Standard 10080, 7 Tage).
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}'
Mit Steuerung senden Sie JSON-Textnachrichten über denselben WebSocket. Koordinaten sind Anteile (0 bis 1) des Frames, den Sie gerade sehen; alles andere wird ignoriert.
| Nachricht | Wirkung |
|---|---|
{"t":"mouse", | Drücken (down), Loslassen (up) oder move; n ist die Anzahl der Klicks, m sind die Modifier-Tasten (Alt 1, Ctrl 2, Meta 4, Shift 8). |
{"t":"wheel", | An einer Position um eine Anzahl Pixel scrollen. |
{"t":"key", | Eine Taste wird gedrückt oder losgelassen, so wie eine Tastatur es sendet. |
{"t":"text", | Text einfügen, als wäre er getippt (bis zu 5000 Zeichen). |
{"t":"nav",, forward, reload oder {"t":"nav", | Verlauf, Neuladen oder eine http(s)-Adresse öffnen. |
GET /api/v1/browsers/<id> enthält traffic: die 20 Sites mit den meisten Bytes in dieser Session.
Sessions verwalten
GET Eine Session
Status, Traffic, Sekunden und bisherige Kosten der Session. Die Felder sind unterhalb der Anfragen beschrieben.
curl 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \ -H "authorization: Bearer cc_live_..."
GET Ihre Sessions
Ihr Guthaben und Ihre Sessions, die neuesten zuerst: standardmäßig 20, mit limit bis zu 100. Filtern Sie nach Status und nach Notiztext; ältere Einträge blättern Sie mit before zurück, gesetzt auf den createdAt-Wert der zuletzt erhaltenen Session. Klicken Sie in einer Zeile auf Verwenden, um in den anderen Anfragen mit dieser Session zu arbeiten.
curl 'https://www.clearcotelabs.com/api/v1/browsers' \ -H "authorization: Bearer cc_live_..."
PATCH Session beschriften
Setzen oder ändern Sie die note (höchstens 256 Zeichen); null entfernt sie.
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 Session beenden
Eine Session, mit der sich niemand verbunden hat, endet sofort; einen laufenden Browser schließt sein Server innerhalb eines Meldeintervalls, also nach etwa 15 Sekunden.
curl -X DELETE 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \ -H "authorization: Bearer cc_live_..."
Geben Sie einer Session beim Anlegen eine note mit, um sie in der Liste und im Dashboard wiederzufinden. Um eine Session auf demselben Server wie eine frühere zu starten (warme Caches, dieselbe Maschine), übergeben Sie den worker jener Session; ist dieser Server voll oder offline, startet die Session auf einem anderen Server, und ihre warnings weisen darauf hin.
Eine Session endet außerdem, wenn Sie den Browser schließen oder die Verbindung trennen, und wenn eines der unten genannten Limits erreicht ist. Eine Stop-Anfrage beendet eine Session, mit der sich niemand verbunden hat, sofort; einen laufenden Browser schließt sein Server innerhalb eines Meldeintervalls, also nach etwa 15 Sekunden. GET antwortet mit:
{
"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
}| status | Bedeutung |
|---|---|
pending | Created; 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). |
active | A browser is running and reporting usage. |
lost | No 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. |
ended | Closed: 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. |
expired | Nobody connected before expiresAt (45 seconds after creating it). Never billed. |
queue zeigt, wo ein startender Browser in der Start-Warteschlange seines Servers steht, sodass ein voller Moment als Platz in der Schlange erscheint statt als langsamer Connect. Auch die Antwort beim Anlegen enthält eine Schätzung: "queue": { "position": 3, "etaSec": 6 }, also wo sich der Browser einreihen würde, wenn Sie jetzt verbinden (beide null, wenn der Server keine Warteschlange meldet).
| queue-Feld | Bedeutung |
|---|---|
state | waiting_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. |
position | 1-based place in the server's waiting list while queued, else null. |
ahead | How many browsers start before this one: position - 1 while queued, 0 while launching, else null. |
etaSec | Estimated 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. |
updatedAt | When the server last reported its queue (ISO time), or null when it has not in the last 30 seconds. |
Der Listenaufruf GET /api/v1/browsers liefert { balanceEur, sessions: [...] } mit denselben Session-Objekten, die neuesten zuerst.
Browser offen halten und neu verbinden
Standardmäßig endet eine Session, sobald Ihr Client die Verbindung trennt. Starten Sie sie mit keepAlive: true, läuft der Browser stattdessen weiter, mit seinen Tabs, Cookies und seiner Exit-IP. So kann ein späteres Skript (oder dasselbe nach einem Absturz oder einem zugeklappten Laptop) dort weitermachen, wo das letzte aufgehört hat:
POST Neu verbinden
Eine neue, einmalig gültige Connect-URL für eine laufende keepAlive-Session (innerhalb von 45 Sekunden verbinden). Mit Verbinden übernehmen Sie den Browser von dieser Seite aus wieder, samt allen Tabs.
curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/connect' \ -H "authorization: Bearer cc_live_..."
- Sie lassen ihn weiterlaufen, indem Sie die Verbindung trennen: mit
browser.close()in Playwright (überconnectOverCDPtrennt das nur die Verbindung), mitbrowser.disconnect()in Puppeteer oder indem Sie einfach Ihren Prozess beenden. - Sie beenden ihn mit
DELETE /api/v1/browsers/<id>oder indem Sie den CDP-BefehlBrowser.closesenden: Das tutbrowser.close()in Puppeteer, in Playwright geht es mitawait (await browser.newBrowserCDPSession()).send("Browser.close"). Bis dahin belegt er einen Platz in Ihrem Concurrency-Limit. - Immer nur ein Client: Ein Reconnect, während ein anderer Client verbunden ist, wird mit
409abgelehnt, ebenso einer für eine Session, die ohnekeepAlivegestartet wurde. - Die Limits gelten auch, während niemand verbunden ist:
idleTimeoutSec(für einen Browser, zu dem Sie zurückkehren wollen, auf bis zu 1800 erhöhen),timeoutSec,maxGbund Ihr Guthaben. Eine offen gelassene Seite lädt weiter ihren Hintergrund-Traffic, der wie jeder andere berechnet wird.