API-V8-Referenz

Starte eine Session, teile sie, verfolge ihren Status, beende sie und prüfe deine Nutzung.

Erstelle deinen API-Schlüssel unter Erweitert auf der Seite Agenten. Dein Konto braucht dafür programmatischen Zugriff.

Mit authentifizierten HTTPS-Anfragen startest du Sessions. Eine Session wird sofort angenommen und startet im Hintergrund: Verfolge ihren Status, bis sie läuft, teile ihren Link mit der Person, die sie ansehen soll, und beende sie, wenn du fertig bist.

Basis-URL

Alle Pfade auf dieser Seite beziehen sich auf diese Adresse.

https://api.browser.lol/v8

Authentifizierung

Sende deinen API-Schlüssel als Bearer-Token im Header Authorization.

Authorization: Bearer YOUR_API_KEY
Wichtig: Halte deinen API-Schlüssel geheim. Sende Anfragen von deinem Server aus und lege den Schlüssel nie im Browsercode offen.

Antworten

Die Endpunkte antworten mit HTTP 200 und einem JSON-Body, dessen status sagt, wie die Anfrage ausgegangen ist. Entscheide anhand von status, nicht anhand des HTTP-Codes, und zeige message an, wenn der Status nicht ok ist. Nur die Prüfungen für Authentifizierung und Ratenbegrenzung können mit einem anderen HTTP-Code antworten.

ok
Die Anfrage war erfolgreich.
denied
Die Anfrage wurde abgelehnt, zum Beispiel wegen eines ungültigen Schlüssels, einer unbekannten Session oder eines ungültigen Felds.
upgrade
Dein Plan umfasst nicht, was die Anfrage verlangt, oder eine seiner Grenzen ist erreicht. Ein Plan, der es umfasst, löst das.
insecure
Eine Sicherheits- oder Ratenprüfung ist fehlgeschlagen. reason nennt die Prüfung.
error
Bei uns ist etwas schiefgelaufen. Versuche es später noch einmal.

Beispiele

{"status": "denied", "message": "Unsupported VPN location"}
{"status": "upgrade", "message": "..."}
{"status": "insecure", "reason": "rate_limited", "message": "..."}
{"status": "error", "message": "..."}

Browser und Standorte

GET/v8/image

Listet die Browser auf, die du starten kannst, und die Ausgangsstandorte, die du wählen kannst. Dieser Endpunkt braucht keinen API-Schlüssel.

  • images[].id ist der Wert für browser, wenn du eine Session startest; enabled sagt, ob der Browser gerade starten kann.
  • vpnLocations[] listet jedes Land mit code und seine Städte in cities[].code. Beide Codes funktionieren als country.
  • residential.countries listet die Länder, die eine Residential-Verbindung nutzen kann; null bedeutet alle Länder.

Beispielanfrage

curl https://api.browser.lol/v8/image

Antwort (gekürzt)

{
  "status": "ok",
  "images": [
    { "id": "chrome", "name": "Chrome", "enabled": true, ... }
  ],
  "vpnLocations": [
    {
      "code": "uk",
      "name": "United Kingdom",
      "default": "uk-lon",
      "cities": [{ "code": "uk-lon", "location": "London" }, ...]
    }
  ],
  "residential": { "configured": true, "countries": null }
}

Session starten

POST/v8/vm/create

Nimmt eine neue Session an und gibt sofort ihre ID zurück. Die Session wird im Hintergrund vorbereitet.

JSON-Felder der Anfrage

browserPflichtfeld
Browser-ID aus GET /image.
urloptional
Seite, die zuerst geöffnet wird, höchstens 10 000 Zeichen.
languageoptional
Sprache der Browseroberfläche, zum Beispiel en oder de. Standard ist deine Kontoeinstellung, sonst en.
layoutoptional
Tastaturlayout, zum Beispiel us oder de. Standard ist deine Kontoeinstellung, sonst us.
countryoptional
Ausgangsstandort: ein Ländercode wie us, de oder uk oder ein Städtecode wie us-dal, genau so, wie GET /image sie auflistet. Mit auto wählt der Dienst. Setzt Standortzugriff voraus.
egressoptional
Setze residential, um über eine Residential-Verbindung zu surfen. Setzt Residential-Daten in deinem Plan voraus; von country zählt nur das Land.
shareLanguageoptional
Sprache des Viewers im Freigabelink: en, de, fr, es, it, pt oder ja. Standard ist en.
callbackUrloptional
HTTP- oder HTTPS-Adresse, die der Viewer öffnet, wenn jemand die Session oder ihren Endbildschirm verlässt, höchstens 2000 Zeichen. Ohne Angabe kehrt der Viewer zur Startseite zurück.
idempotencyKeyoptional
Dein eigener Schlüssel mit 1 bis 128 Zeichen. Schickst du dieselbe Anfrage mit demselben Schlüssel noch einmal, kommt die erste erfolgreiche Antwort zurück, statt dass eine zweite Session startet.

Beispielanfrage

curl -X POST https://api.browser.lol/v8/vm/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"browser": "chrome", "url": "https://example.com", "country": "uk"}'

Antwort

{
  "status": "ok",
  "vmId": "brl-v-v7-abc123...",
  "shareUrl": "https://browser.lol/en/s?LINK_ID",
  "shareUrlPath": "/en/s?LINK_ID",
  "quota": {
    "running_session_limit": 2,
    "running_sessions_used": 1,
    "running_sessions_remaining": 1,
    "cycle_session_limit": null,
    "cycle_sessions_used": 42,
    "cycle_sessions_remaining": null,
    "cycle_start": "2026-10-01"
  }
}
Die Antwort kommt, sobald die Session angenommen ist. Die Session beginnt im Status starting und wechselt zu running, sobald sie bereit ist, oder zu error, wenn sie nicht starten kann. shareUrl ist enthalten, wenn der Freigabelink erstellt werden konnte.

Status einer Session

GET/v8/vm/data?id=VM_ID

Gibt deine Sessions des letzten Monats zurück, die neuste zuerst. Übergib die vmId aus dem Start als id, um nur diese Session zu erhalten.

Beispielanfrage

curl "https://api.browser.lol/v8/vm/data?id=VM_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Antwort (gekürzt)

{
  "status": "ok",
  "data": [
    {
      "id": "brl-v-v7-*******...abc123",
      "status": "running",
      "name": "Chrome",
      "created": "2026-10-01T12:00:00.000Z",
      ...
    }
  ]
}
Frage alle paar Sekunden ab, bis data[0].status den Wert running hat. error bedeutet, dass die Session nicht starten konnte; stopping, suspended und deleted bedeuten, dass sie beendet ist. Eine leere data-Liste heisst, dass es diese Session nicht gibt. Die id in der Antwort ist teilweise maskiert.

Session teilen

Gib die shareUrl aus dem Start an die Person weiter, die den Viewer öffnen soll. Die Seite wartet, bis die Session bereit ist. Behandle den Link wie ein Passwort für die Session.

Ein Freigabelink gehört zu einer Session und funktioniert nicht mehr, sobald diese Session gelöscht ist.
Der Freigabelink enthält ein Sprachsegment (en) für den Viewer. Du kannst es durch de, fr, es, it, pt oder ja ersetzen oder beim Start shareLanguage setzen.

Session beenden

POST/v8/vm/remove

Beendet eine Session. Übergib ihre vmId als id. Auch eine Session, die schon beendet ist, antwortet mit ok.

Beispielanfrage

curl -X POST https://api.browser.lol/v8/vm/remove \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "VM_ID"}'

Antwort

{"status": "ok"}

Konto und Nutzung

GET/v8/user/api

Gibt deine Kontaktadresse zurück, ob programmatischer Zugriff aktiv ist, und deine Nutzung von Sessions und Residential-Daten.

Beispielanfrage

curl https://api.browser.lol/v8/user/api \
  -H "Authorization: Bearer YOUR_API_KEY"

Antwort

{
  "status": "ok",
  "contact": "[email protected]",
  "feature_programmatic_access": true,
  "has_plan": true,
  "cycle_start": "2026-10-01",
  "cycle_session_limit": null,
  "cycle_sessions_used": 42,
  "cycle_sessions_remaining": null,
  "running_session_limit": 2,
  "running_sessions_used": 1,
  "running_sessions_remaining": 1,
  "residential_cycle_mb_limit": 6000,
  "residential_bytes_used_cycle": 104857600,
  "pools": [
    {
      "subscription_id": "brl-s-v7-abc123...",
      "plan_id": "browser-premium",
      "plan_name": "Premium",
      "cycle_start": "2026-10-01",
      "cycle_session_limit": null,
      "cycle_sessions_used": 42,
      "cycle_sessions_remaining": null,
      "running_session_limit": 2,
      "running_sessions_used": 1,
      "running_sessions_remaining": 1,
      "residential_cycle_mb_limit": 6000,
      "residential_bytes_used_cycle": 104857600
    }
  ]
}

Nutzungsfelder

cycle_session_limit
Höchstzahl an Sessions im aktuellen Zyklus, oder null ohne Obergrenze.
cycle_sessions_used
Im aktuellen Zyklus gestartete Sessions.
cycle_sessions_remaining
Verbleibende Sessions im aktuellen Zyklus, oder null ohne Obergrenze.
running_session_limit
Höchstzahl gleichzeitiger Sessions.
running_sessions_used
Sessions, die gerade als laufend zählen.
running_sessions_remaining
Freie Plätze unter dieser Grenze. Weitere Prüfungen beim Start gelten trotzdem.
cycle_start
Startdatum des aktuellen Zyklus (JJJJ-MM-TT).
residential_cycle_mb_limit
Enthaltene Residential-Daten pro Zyklus in MB, oder null, wenn kein Kontingent gilt.
residential_bytes_used_cycle
Im aktuellen Zyklus genutzte Residential-Daten in Byte.
pools
Dieselben Zähler für jedes Abo hinter den Summen, mit subscription_id, plan_id und plan_name.

Nur Nutzung

GET/v8/user/quota

Gibt dieselben Nutzungsfelder wie GET /user/api zurück, ohne Kontaktadresse und ohne Angabe zum programmatischen Zugriff.

Beispielanfrage

curl https://api.browser.lol/v8/user/quota \
  -H "Authorization: Bearer YOUR_API_KEY"

Antwort

{
  "status": "ok",
  "has_plan": true,
  "cycle_start": "2026-10-01",
  "cycle_session_limit": null,
  "cycle_sessions_used": 42,
  "cycle_sessions_remaining": null,
  "running_session_limit": 2,
  "running_sessions_used": 1,
  "running_sessions_remaining": 1,
  "residential_cycle_mb_limit": 6000,
  "residential_bytes_used_cycle": 104857600,
  "pools": [
    {
      "subscription_id": "brl-s-v7-abc123...",
      "plan_id": "browser-premium",
      "plan_name": "Premium",
      "cycle_start": "2026-10-01",
      "cycle_session_limit": null,
      "cycle_sessions_used": 42,
      "cycle_sessions_remaining": null,
      "running_session_limit": 2,
      "running_sessions_used": 1,
      "running_sessions_remaining": 1,
      "residential_cycle_mb_limit": 6000,
      "residential_bytes_used_cycle": 104857600
    }
  ]
}