Referencia de la API v8

Inicia una sesión, compártela, sigue su estado, termínala y consulta tu uso.

Crea tu clave de API en Avanzado, en la página Agentes. Tu cuenta necesita acceso programático.

Envía peticiones HTTPS autenticadas para iniciar sesiones. Cada sesión se acepta al momento y arranca en segundo plano: sigue su estado hasta que esté en marcha, comparte su enlace con quien deba verla y termínala cuando acabes.

URL base

Todas las rutas de esta página son relativas a esta dirección.

https://api.browser.lol/v8

Autenticación

Envía tu clave de API como token Bearer en la cabecera Authorization.

Authorization: Bearer YOUR_API_KEY

Importante: Mantén tu clave de API en secreto. Haz las peticiones desde tu servidor y no expongas nunca la clave en código del cliente.

Respuestas

Los endpoints responden con HTTP 200 y un cuerpo JSON cuyo status indica cómo ha ido la petición. Decide según status, no según el código HTTP, y muestra message cuando no sea ok. Solo las comprobaciones de autenticación y de límite de peticiones pueden responder con otro código HTTP.

ok: La petición se ha completado.
denied: La petición se ha rechazado, por ejemplo por una clave no válida, una sesión desconocida o un campo no válido.
upgrade: Tu plan no incluye lo que pide la petición, o se ha alcanzado uno de sus límites. Un plan que lo incluya lo resuelve.
insecure: Ha fallado una comprobación de seguridad o de frecuencia. reason indica cuál.
error: Algo ha fallado por nuestra parte. Vuelve a intentarlo más tarde.

Ejemplos

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

Navegadores y ubicaciones

GET/v8/image

Lista los navegadores que puedes iniciar y las ubicaciones de salida que puedes elegir. Este endpoint no necesita clave de API.

images[].id es el valor de browser al iniciar una sesión; enabled indica si el navegador puede arrancar ahora.
vpnLocations[] lista cada país por su code con sus ciudades en cities[].code. Ambos códigos sirven como country.
residential.countries lista los países que puede usar una conexión residencial; null significa todos.

Petición de ejemplo

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

Respuesta (resumida)

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

Iniciar una sesión

POST/v8/vm/create

Acepta una nueva sesión y devuelve su ID al momento. La sesión se prepara en segundo plano.

Campos JSON de la petición

browserobligatorio: ID del navegador según GET /image.
urlopcional: Página que se abre primero, hasta 10.000 caracteres.
languageopcional: Idioma de la interfaz del navegador, por ejemplo en o de. Por defecto, el ajuste de tu cuenta o, si no hay, en.
layoutopcional: Distribución del teclado, por ejemplo us o de. Por defecto, el ajuste de tu cuenta o, si no hay, us.
countryopcional: Ubicación de salida: un código de país como us, de o uk, o un código de ciudad como us-dal, tal como los lista GET /image. Con auto elige el servicio. Requiere acceso a ubicaciones.
egressopcional: Indica residential para navegar con una conexión residencial. Requiere datos residenciales en tu plan; de country solo se usa el país.
shareLanguageopcional: Idioma del visor en el enlace para compartir: en, de, fr, es, it, pt o ja. Por defecto, en.
callbackUrlopcional: Dirección HTTP o HTTPS que abre el visor cuando alguien sale de la sesión o de su pantalla final, hasta 2.000 caracteres. Sin ella, el visor vuelve a la página de inicio de sesiones.
idempotencyKeyopcional: Tu propia clave de 1 a 128 caracteres. Si repites la petición con la misma clave, recibes la primera respuesta correcta en lugar de iniciar una segunda sesión.

Petición de ejemplo

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

Respuesta

{
  "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 respuesta llega en cuanto se acepta la sesión. La sesión empieza en el estado starting y pasa a running cuando está lista, o a error si no puede arrancar. shareUrl aparece cuando se ha podido crear el enlace para compartir.

Estado de una sesión

GET/v8/vm/data?id=VM_ID

Devuelve tus sesiones del último mes, de la más reciente a la más antigua. Pasa el vmId de la petición de inicio como id para obtener solo esa sesión.

Petición de ejemplo

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

Respuesta (resumida)

{
  "status": "ok",
  "data": [
    {
      "id": "brl-v-v7-*******...abc123",
      "status": "running",
      "name": "Chrome",
      "created": "2026-10-01T12:00:00.000Z",
      ...
    }
  ]
}

Consulta cada pocos segundos hasta que data[0].status sea running. error significa que la sesión no pudo arrancar; stopping, suspended y deleted significan que ha terminado. Una lista data vacía significa que esa sesión no existe. El id de la respuesta aparece parcialmente oculto.

Terminar una sesión

POST/v8/vm/remove

Termina una sesión. Pasa su vmId como id. Una sesión que ya ha terminado también responde ok.

Petición de ejemplo

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

Respuesta

{"status": "ok"}

Cuenta y uso

GET/v8/user/api

Devuelve tu dirección de contacto, si el acceso programático está activo y tu uso de sesiones y de datos residenciales.

Petición de ejemplo

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

Respuesta

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

Campos de uso

cycle_session_limit: Máximo de sesiones en el ciclo actual, o null si no hay tope.
cycle_sessions_used: Sesiones iniciadas en el ciclo actual.
cycle_sessions_remaining: Sesiones que quedan en el ciclo actual, o null si no hay tope.
running_session_limit: Máximo de sesiones simultáneas.
running_sessions_used: Sesiones que cuentan ahora como activas.
running_sessions_remaining: Plazas libres bajo ese límite. Al iniciar se aplican igualmente otras comprobaciones.
cycle_start: Fecha de inicio del ciclo actual (AAAA-MM-DD).
residential_cycle_mb_limit: Datos residenciales incluidos por ciclo, en MB, o null si no se aplica ninguna cuota.
residential_bytes_used_cycle: Datos residenciales usados en el ciclo actual, en bytes.
pools: Los mismos contadores para cada suscripción que hay detrás de los totales, con su subscription_id, plan_id y plan_name.

Solo el uso

GET/v8/user/quota

Devuelve los mismos campos de uso que GET /user/api, sin la dirección de contacto ni el indicador de acceso programático.

Petición de ejemplo

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

Respuesta

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

URL base

Autenticación

Respuestas

Ejemplos

Navegadores y ubicaciones

Petición de ejemplo

Respuesta (resumida)

Iniciar una sesión

Campos JSON de la petición

Petición de ejemplo

Respuesta

Estado de una sesión

Petición de ejemplo

Respuesta (resumida)

Compartir la sesión

Terminar una sesión

Petición de ejemplo

Respuesta

Cuenta y uso

Petición de ejemplo

Respuesta

Campos de uso

Solo el uso

Petición de ejemplo

Respuesta