API v8 reference

Start a session, share it, follow its status, end it and check your usage.

Create your API key under Advanced on the Agents page. Your account needs programmatic access.

Send authenticated HTTPS requests to start sessions. A session is accepted at once and starts in the background: follow its status until it is running, share its link with whoever should view it, and end it when you are done.

Base URL

Every path on this page is relative to this address.

https://api.browser.lol/v8

Authentication

Pass your API key as a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY
Important: Keep your API key secret. Send requests from your server, and never expose the key in client-side code.

Responses

Endpoints answer with HTTP 200 and a JSON body whose status says how the request went. Branch on status, not on the HTTP code, and show message when it is not ok. Only the authentication and rate-limit checks can answer with another HTTP code.

ok
The request succeeded.
denied
The request was refused, for example because of an invalid key, an unknown session or an invalid field.
upgrade
Your plan does not include what the request asks for, or one of its limits is reached. A plan that includes it resolves this.
insecure
A security or rate check failed. reason names the check.
error
Something went wrong on our side. Try again later.

Examples

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

Browsers and locations

GET/v8/image

Lists the browsers you can start and the exit locations you can choose. This endpoint needs no API key.

  • images[].id is the value for browser when you start a session; enabled says whether the browser can start right now.
  • vpnLocations[] lists every country by code with its cities in cities[].code. Either code works as country.
  • residential.countries lists the countries a residential connection can use; null means every country.

Example request

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

Response (shortened)

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

Start a session

POST/v8/vm/create

Accepts a new session and returns its ID at once. The session is prepared in the background.

JSON request fields

browserrequired
Browser ID from GET /image.
urloptional
Page to open first, up to 10,000 characters.
languageoptional
Browser interface language, for example en or de. Defaults to your account setting, otherwise en.
layoutoptional
Keyboard layout, for example us or de. Defaults to your account setting, otherwise us.
countryoptional
Exit location: a country code such as us, de or uk, or a city code such as us-dal, exactly as GET /image lists them. auto lets the service choose. Requires location access.
egressoptional
Set to residential to browse through a residential connection. Requires residential data in your plan; only the country part of country is used.
shareLanguageoptional
Viewer language in the share link: en, de, fr, es, it, pt or ja. Defaults to en.
callbackUrloptional
HTTP or HTTPS address the viewer opens when someone leaves the session or its ended screen, up to 2,000 characters. Without it, the viewer returns to the launch page.
idempotencyKeyoptional
Your own key of 1 to 128 characters. Sending the same request again with the same key returns the first successful response instead of starting a second session.

Example request

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

Response

{
  "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"
  }
}
The answer arrives as soon as the session is accepted. The session starts in status starting and changes to running when it is ready, or to error if it cannot start. shareUrl is included when the share link could be created.

Session status

GET/v8/vm/data?id=VM_ID

Returns your sessions from the last month, newest first. Pass the vmId from the start call as id to get only that session.

Example request

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

Response (shortened)

{
  "status": "ok",
  "data": [
    {
      "id": "brl-v-v7-*******...abc123",
      "status": "running",
      "name": "Chrome",
      "created": "2026-10-01T12:00:00.000Z",
      ...
    }
  ]
}
Poll every few seconds until data[0].status is running. error means the session could not start; stopping, suspended and deleted mean it has ended. An empty data list means there is no such session. The id in the answer is partly masked.

Share the session

Give the shareUrl from the start call to the person who should open the viewer. The page waits until the session is ready. Treat the link like a password for the session.

A share link belongs to one session and stops working when that session is deleted.
The share link contains a language segment (en) for the viewer. You can replace it with de, fr, es, it, pt or ja, or set shareLanguage when you start the session.

End a session

POST/v8/vm/remove

Ends a session. Pass its vmId as id. Ending a session that has already ended also answers ok.

Example request

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

Response

{"status": "ok"}

Account and usage

GET/v8/user/api

Returns your contact address, whether programmatic access is on, and your session and residential data usage.

Example request

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

Response

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

Usage fields

cycle_session_limit
Maximum sessions in the current cycle, or null when there is no cap.
cycle_sessions_used
Sessions started in the current cycle.
cycle_sessions_remaining
Sessions left in the current cycle, or null when there is no cap.
running_session_limit
Maximum sessions at the same time.
running_sessions_used
Sessions currently counted as running.
running_sessions_remaining
Slots left under that limit. Other launch checks still apply.
cycle_start
Start date of the current cycle (YYYY-MM-DD).
residential_cycle_mb_limit
Residential data included per cycle, in MB, or null when no allowance applies.
residential_bytes_used_cycle
Residential data used in the current cycle, in bytes.
pools
The same meters for each subscription behind the totals, with its subscription_id, plan_id and plan_name.

Usage only

GET/v8/user/quota

Returns the same usage fields as GET /user/api, without the contact address and the programmatic access flag.

Example request

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

Response

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