Sessions-API-Referenz
Browser-Sessions per HTTP anlegen, abfragen, verlängern und freigeben: der volle Create-Body, die zwei Keep-alive-Kappungen und jedes Feld des Session-Datensatzes.
Zuletzt aktualisiert:
Eine Session ist ein gehärteter Browser-Container mit einer Frist. Die vier Endpunkte auf dieser Seite legen sie an, lesen ihren Datensatz, verlängern sie und geben sie frei. Jeder Aufruf authentifiziert sich mit einem API-Schlüssel als Bearer-Token im Authorization-Header, und Request-Bodies sind strikt: Ein vertipptes Feld kommt als 400 invalid_request zurück, statt still ignoriert zu werden.
/v1/sessions
Legt eine Session an; der minimale Body ist `{}`, jedes Feld unten ist optional.
Create-Body
| Name | Typ | Beschreibung |
|---|---|---|
shape
|
object | Browser-Form: `viewport` (Standard 1440×900), `locale` (Standard `de-DE`), `timezone` (Standard `Europe/Berlin`), `headless` (Standard `true`) und `extraArgs` von der Allowlist. Ein unzulässiges Argument wird mit `disallowed_browser_arg` abgelehnt. |
profileId
|
string | Stellt Cookies, Storage und Anmeldezustand des benannten Profils im Browser wieder her. Ein noch nicht existierendes Profil wird dabei angelegt, geprüft gegen dein Tarifkontingent; der Zustand wird beim Teardown erneut erfasst. |
credentialIds
|
string[] | Tresor-Zugangsdaten, die die Session nutzen darf; jeder Wert wird ausschließlich auf der Site freigegeben, für die er hinterlegt wurde. |
egress
|
object | `allowDomains` und `denyDomains` beschränken, wohin der Browser Verbindungen aufbauen darf. |
recording
|
object | `enabled` (Standard `true`) und `retentionHours` (Standard 24) steuern die Aufzeichnung der Session. |
ttlSeconds
|
integer |
Anfängliche Lebensdauer, 30 bis 259200 Sekunden. Die Tarif-Obergrenze gilt zusätzlich über `maxLifetimeAt`.
Standard: 900
|
keepAlive.idleTimeoutSeconds
|
integer | Gibt eine Session frei, die niemand nutzt. Das ist eine andere Zahl als die Frist: `expiresAt` und `maxLifetimeAt` begrenzen auch eine beschäftigte Session. |
keepAlive.checkpointSeconds
|
integer | Intervall, in dem der Session-Zustand gesichert wird; der jüngste Zeitpunkt erscheint als `checkpointedAt` im Datensatz. |
poolId
|
string | Beansprucht einen Browser aus einem reservierten Pool. Eine Pool-Session fällt nie auf einen Kaltstart zurück und darf keine andere Form verlangen — eine Abweichung wird abgelehnt. |
metadata
|
object | Eigene, frei wählbare Labels, die im Session-Datensatz zurückgegeben werden. |
/v1/sessions/:id
Liefert den Session-Datensatz, inklusive der `connectUrl` für CDP-Clients, solange die Session `ready` ist.
/v1/sessions
Die offenen Sessions der Organisation, aus der Registry hydriert, damit ein neu verbundener Client seine Handles wiederfinden und anbinden kann.
/v1/sessions/:id/connect-token
Eine frische `connectUrl` mit neuem Fünf-Minuten-Zugriffstoken, für einen Aufrufer, der länger gewartet hat, als das Token der Create- oder Get-Antwort lebt. Session-gebunden: Es öffnet keine andere Session.
/v1/sessions/:id/watch-link
Ein anmeldefreier Viewer-Link, nur lesend, sofern `allowTakeover` nicht wahr ist, gültig `ttlSeconds` (60–3600, Standard 3600). Antwortet mit `capacity_unavailable` auf einer Installation ohne öffentliche Basis-URL.
/v1/sessions/:id/keepalive
Verlängert die Frist der Session; der Body ist `{}` oder nennt ein neues `ttlSeconds`.
Keep-alive-Body
| Name | Typ | Beschreibung |
|---|---|---|
ttlSeconds
|
integer | Die gewünschte Verlängerung, gerechnet ab jetzt, innerhalb der Grenzen von 30 bis 259200 Sekunden. Ohne Angabe gilt die Standard-Verlängerung. |
Die zwei Kappungen lesen
Die Antwort enthält die aktualisierte Session plus zwei Booleans, die sagen, was wirklich passiert ist. clampedToMaxLifetime heißt: Die Session steht an der Obergrenze, die ihr Tarif bei der Erstellung festgelegt hat — kein weiterer Keep-alive hilft, plane also eine frische Session. clampedToPlanLimit heißt: Genau diese Verlängerung wurde auf das gestutzt, was der Tarif gerade erlaubt; die Session läuft weiter, und du fragst später einfach erneut. maxLifetimeAt selbst bewegt sich nie.
/v1/sessions/:id
Gibt die Session und ihren Container frei; ein benanntes Profil wird auch auf diesem Teardown-Pfad erfasst.
Felder des Session-Datensatzes
Responses sind tolerant: Ein neuerer Server darf Felder ergänzen, also toleriere unbekannte.
| Name | Typ | Beschreibung |
|---|---|---|
connectUrl
|
string | Ein `wss://`-CDP-Endpunkt mit einem `?t=`-Zugriffstoken, solange die Session `ready` ist; sonst null. Das Token wird beim WebSocket-Upgrade geprüft und lebt fünf Minuten ab der Antwort; behandle die URL als Berechtigungsnachweis. |
connectUrlExpiresAt
|
timestamp | Wann das Token in `connectUrl` den Socket nicht mehr öffnet. Null, wenn es kein Token gibt. Seit Protokoll 1.4. |
status
|
string | Offenes Enum: heute `pending`, `ready`, `releasing`, `released`, `failed` — behalte einen Default-Zweig für Werte eines neueren Servers. |
warmStart
|
boolean | Wahr, wenn der Browser aus einem Pool oder dem Warm-Pool kam statt aus einem kalten Container-Start. |
readyAt
|
timestamp | Wann der Browser nutzbar wurde. Die Abrechnungsuhr startet hier, nicht bei der Annahme. |
expiresAt
|
timestamp | Die aktuelle Frist; ein Keep-alive schiebt sie nach vorn. |
maxLifetimeAt
|
timestamp | Die bei der Erstellung aus dem Tarif gesetzte Obergrenze. Ein Keep-alive bewegt sie nie. |
shutdownReason
|
string | Warum die Session endete, als offenes Enum — Protokoll 1.2.0 hat `idle_timeout` ergänzt, switche also mit Default-Fall. |
checkpointedAt
|
timestamp | Wann der Session-Zustand zuletzt gesichert wurde, sofern `keepAlive.checkpointSeconds` gesetzt war. |
lastActiveAt
|
timestamp | Wann zuletzt etwas die Session genutzt hat — die Grundlage des Idle-Timeouts. |
Anlegen, lesen, freigeben
Ein Durchlauf über den Lebenszyklus: Anlegen mit Metadaten, die Zeitfelder des Datensatzes lesen, freigeben.
Voraussetzungen: api-key
BASE="https://browserberg.com"
AUTH="Authorization: Bearer $BROWSERBERG_API_KEY"
JSON="Content-Type: application/json"
CREATED=$(curl -s -X POST "$BASE/v1/sessions" -H "$AUTH" -H "$JSON" -d '{
"ttlSeconds": 120,
"metadata": { "purpose": "reference walkthrough" }
}')
ID=$(echo "$CREATED" | python3 -c 'import json,sys; print(json.load(sys.stdin)["session"]["id"])')
curl -s "$BASE/v1/sessions/$ID" -H "$AUTH" \
| python3 -c 'import json,sys; s = json.load(sys.stdin)["session"]; print(json.dumps({
"status": s["status"], "warmStart": s["warmStart"], "readyAt": s["readyAt"],
"expiresAt": s["expiresAt"], "maxLifetimeAt": s["maxLifetimeAt"]}, indent=2))'
curl -s -X DELETE "$BASE/v1/sessions/$ID" -H "$AUTH" > /dev/null
echo "released"{
"status": "ready",
"warmStart": true,
"readyAt": "2026-01-01T00:00:00.000Z",
"expiresAt": "2026-01-01T00:00:00.000Z",
"maxLifetimeAt": "2026-01-01T00:00:00.000Z"
}
released