Riferimento API v8

Avvia una sessione, condividila, seguine lo stato, chiudila e controlla il tuo utilizzo.

Crea la tua chiave API in Avanzate, nella pagina Agenti. Il tuo account deve avere l'accesso programmatico.

Invia richieste HTTPS autenticate per avviare sessioni. Ogni sessione viene accettata subito e parte in background: seguine lo stato finché non è attiva, condividi il suo link con chi deve vederla e chiudila quando hai finito.

URL di base

Tutti i percorsi di questa pagina sono relativi a questo indirizzo.

https://api.browser.lol/v8

Autenticazione

Passa la tua chiave API come Bearer token nell'header Authorization.

Authorization: Bearer YOUR_API_KEY
Importante: Tieni segreta la chiave API. Invia le richieste dal tuo server e non inserire mai la chiave nel codice eseguito dal browser.

Risposte

Gli endpoint rispondono con HTTP 200 e un corpo JSON il cui status dice com'è andata la richiesta. Decidi in base a status, non al codice HTTP, e mostra message quando non vale ok. Solo i controlli di autenticazione e di limitazione delle richieste possono rispondere con un altro codice HTTP.

ok
La richiesta è andata a buon fine.
denied
La richiesta è stata rifiutata, per esempio per una chiave non valida, una sessione sconosciuta o un campo non valido.
upgrade
Il tuo piano non include ciò che la richiesta chiede, oppure è stato raggiunto uno dei suoi limiti. Un piano che lo include risolve il problema.
insecure
Un controllo di sicurezza o di frequenza non è stato superato. reason indica quale.
error
Qualcosa è andato storto da parte nostra. Riprova più tardi.

Esempi

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

Browser e località

GET/v8/image

Elenca i browser che puoi avviare e le località di uscita che puoi scegliere. Questo endpoint non richiede una chiave API.

  • images[].id è il valore di browser quando avvii una sessione; enabled indica se il browser può partire adesso.
  • vpnLocations[] elenca ogni Paese con il suo code e le sue città in cities[].code. Entrambi i codici valgono come country.
  • residential.countries elenca i Paesi che una connessione residenziale può usare; null significa tutti.

Richiesta di esempio

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

Risposta (abbreviata)

{
  "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 }
}

Avviare una sessione

POST/v8/vm/create

Accetta una nuova sessione e ne restituisce subito l'ID. La sessione viene preparata in background.

Campi JSON della richiesta

browserobbligatorio
ID del browser da GET /image.
urlfacoltativo
Pagina da aprire per prima, fino a 10.000 caratteri.
languagefacoltativo
Lingua dell'interfaccia del browser, per esempio en o de. Predefinita: l'impostazione del tuo account, altrimenti en.
layoutfacoltativo
Layout della tastiera, per esempio us o de. Predefinito: l'impostazione del tuo account, altrimenti us.
countryfacoltativo
Località di uscita: un codice Paese come us, de o uk, oppure un codice città come us-dal, esattamente come li elenca GET /image. Con auto sceglie il servizio. Richiede l'accesso alle località.
egressfacoltativo
Imposta residential per navigare tramite una connessione residenziale. Richiede dati residenziali nel tuo piano; di country conta solo il Paese.
shareLanguagefacoltativo
Lingua del visualizzatore nel link di condivisione: en, de, fr, es, it, pt o ja. Predefinita: en.
callbackUrlfacoltativo
Indirizzo HTTP o HTTPS che il visualizzatore apre quando qualcuno lascia la sessione o la sua schermata finale, fino a 2.000 caratteri. Senza, il visualizzatore torna alla pagina di avvio.
idempotencyKeyfacoltativo
Una tua chiave da 1 a 128 caratteri. Se ripeti la richiesta con la stessa chiave, ricevi la prima risposta riuscita invece di avviare una seconda sessione.

Richiesta di esempio

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

Risposta

{
  "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"
  }
}
La risposta arriva non appena la sessione è accettata. La sessione parte con stato starting e passa a running quando è pronta, oppure a error se non riesce a partire. shareUrl è presente quando è stato possibile creare il link di condivisione.

Stato di una sessione

GET/v8/vm/data?id=VM_ID

Restituisce le tue sessioni dell'ultimo mese, dalla più recente. Passa il vmId ricevuto all'avvio come id per ottenere solo quella sessione.

Richiesta di esempio

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

Risposta (abbreviata)

{
  "status": "ok",
  "data": [
    {
      "id": "brl-v-v7-*******...abc123",
      "status": "running",
      "name": "Chrome",
      "created": "2026-10-01T12:00:00.000Z",
      ...
    }
  ]
}
Interroga ogni pochi secondi finché data[0].status non vale running. error significa che la sessione non è riuscita a partire; stopping, suspended e deleted significano che è terminata. Un elenco data vuoto significa che la sessione non esiste. L<code>id</code> nella risposta è parzialmente mascherato.

Condividere la sessione

Passa lo shareUrl ricevuto all'avvio a chi deve aprire il visualizzatore. La pagina attende che la sessione sia pronta. Tratta il link come una password della sessione.

Un link di condivisione appartiene a una sola sessione e smette di funzionare quando quella sessione viene eliminata.
Il link di condivisione contiene un segmento di lingua (en) per il visualizzatore. Puoi sostituirlo con de, fr, es, it, pt o ja, oppure impostare shareLanguage all'avvio.

Chiudere una sessione

POST/v8/vm/remove

Chiude una sessione. Passa il suo vmId come id. Anche una sessione già terminata risponde ok.

Richiesta di esempio

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

Risposta

{"status": "ok"}

Account e utilizzo

GET/v8/user/api

Restituisce il tuo indirizzo di contatto, se l'accesso programmatico è attivo e il tuo utilizzo di sessioni e dati residenziali.

Richiesta di esempio

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

Risposta

{
  "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
    }
  ]
}

Campi di utilizzo

cycle_session_limit
Numero massimo di sessioni nel ciclo corrente, oppure null senza limite.
cycle_sessions_used
Sessioni avviate nel ciclo corrente.
cycle_sessions_remaining
Sessioni rimaste nel ciclo corrente, oppure null senza limite.
running_session_limit
Numero massimo di sessioni contemporanee.
running_sessions_used
Sessioni che contano adesso come attive.
running_sessions_remaining
Posti liberi entro quel limite. Restano validi gli altri controlli all'avvio.
cycle_start
Data di inizio del ciclo corrente (AAAA-MM-GG).
residential_cycle_mb_limit
Dati residenziali inclusi per ciclo, in MB, oppure null se non si applica alcuna quota.
residential_bytes_used_cycle
Dati residenziali usati nel ciclo corrente, in byte.
pools
Gli stessi contatori per ogni abbonamento alla base dei totali, con subscription_id, plan_id e plan_name.

Solo utilizzo

GET/v8/user/quota

Restituisce gli stessi campi di utilizzo di GET /user/api, senza indirizzo di contatto e senza l'indicatore di accesso programmatico.

Richiesta di esempio

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

Risposta

{
  "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
    }
  ]
}