API v8 リファレンス

セッションを開始し、共有し、状態を確認して終了し、利用状況を確認できます。

API キーはエージェントページの詳細設定で作成できます。アカウントでプログラムからのアクセスが有効になっている必要があります。

認証付きの HTTPS リクエストで、セッションを開始できます。セッションはすぐに受け付けられ、バックグラウンドで起動します。実行中になるまで状態を確認し、閲覧する人にリンクを共有し、作業が終わったら終了してください。

ベース URL

このページのパスはすべて、このアドレスからの相対パスです。

https://api.browser.lol/v8

認証

API キーを Bearer トークンとして Authorization ヘッダーで送信してください。

Authorization: Bearer YOUR_API_KEY
重要: API キーは秘密にしてください。リクエストはサーバーから送り、クライアント側のコードにキーを含めないでください。

レスポンス

エンドポイントは HTTP 200 と JSON 本文で応答し、status がリクエストの結果を示します。HTTP コードではなく status で処理を分け、ok 以外のときは message を表示してください。別の HTTP コードを返すのは、認証とレート制限のチェックだけです。

ok
リクエストは成功しました。
denied
リクエストは拒否されました。たとえば、キーが無効な場合、セッションが見つからない場合、フィールドが無効な場合です。
upgrade
リクエストの内容がプランに含まれていないか、プランの上限に達しています。それを含むプランにすると解決します。
insecure
セキュリティまたはリクエスト頻度のチェックに失敗しました。reason がどのチェックかを示します。
error
こちら側で問題が発生しました。しばらくしてからもう一度お試しください。

例

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

ブラウザと接続先

GET/v8/image

起動できるブラウザと、選べる出口の場所を一覧で返します。このエンドポイントには API キーは不要です。

  • images[].id はセッション開始時の browser の値です。enabled は、そのブラウザを今すぐ起動できるかどうかを示します。
  • vpnLocations[] は国ごとの code と、その国の都市 (cities[].code) の一覧です。どちらのコードも country に使えます。
  • residential.countries はレジデンシャル接続で使える国の一覧です。null はすべての国を意味します。

リクエスト例

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

レスポンス (一部省略)

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

セッションを開始する

POST/v8/vm/create

新しいセッションを受け付け、その ID をすぐに返します。セッションはバックグラウンドで準備されます。

リクエストの JSON フィールド

browser必須
GET /image で取得したブラウザ ID。
url任意
最初に開くページ。最大 10,000 文字。
language任意
ブラウザの表示言語。例: en、de。既定値はアカウントの設定で、ない場合は en です。
layout任意
キーボード配列。例: us、de。既定値はアカウントの設定で、ない場合は us です。
country任意
出口の場所。us、de、uk などの国コード、または us-dal などの都市コードを、GET /image の一覧どおりに指定します。auto ではサービスが選びます。場所の選択が使えるプランが必要です。
egress任意
residential を指定すると、レジデンシャル接続で閲覧します。プランにレジデンシャルデータが必要で、country は国の部分だけが使われます。
shareLanguage任意
共有リンクで使うビューアの言語: en、de、fr、es、it、pt、ja。既定値は en です。
callbackUrl任意
セッションまたは終了画面から離れるときにビューアが開く HTTP または HTTPS のアドレス。最大 2,000 文字。省略すると、ビューアは起動ページに戻ります。
idempotencyKey任意
1〜128 文字の任意のキー。同じキーで同じリクエストをもう一度送ると、2 つ目のセッションを開始せず、最初の成功レスポンスを返します。

リクエスト例

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

レスポンス

{
  "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"
  }
}
レスポンスはセッションが受け付けられた時点で返ります。セッションは starting の状態で始まり、準備ができると running に、開始できない場合は error に変わります。shareUrl は共有リンクを作成できた場合に含まれます。

セッションの状態

GET/v8/vm/data?id=VM_ID

過去 1 か月のセッションを新しい順に返します。開始時に受け取った vmId を id として渡すと、そのセッションだけを返します。

リクエスト例

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

レスポンス (一部省略)

{
  "status": "ok",
  "data": [
    {
      "id": "brl-v-v7-*******...abc123",
      "status": "running",
      "name": "Chrome",
      "created": "2026-10-01T12:00:00.000Z",
      ...
    }
  ]
}
data[0].status が running になるまで、数秒ごとに確認してください。error は起動できなかったこと、stopping、suspended、deleted は終了したことを示します。data が空の場合、そのセッションは存在しません。レスポンスの id は一部が伏せられています。

セッションを共有する

開始時に受け取った shareUrl を、ビューアを開く人に渡してください。ページはセッションの準備ができるまで待機します。リンクはセッションのパスワードとして扱ってください。

共有リンクは 1 つのセッションに紐づき、そのセッションが削除されると使えなくなります。
共有リンクには、ビューアの言語を示す部分 (en) が含まれます。de、fr、es、it、pt、ja に置き換えるか、開始時に shareLanguage を指定してください。

セッションを終了する

POST/v8/vm/remove

セッションを終了します。vmId を id として渡してください。すでに終了したセッションでも ok を返します。

リクエスト例

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

レスポンス

{"status": "ok"}

アカウントと利用状況

GET/v8/user/api

連絡先メールアドレス、プログラムからのアクセスが有効かどうか、セッションとレジデンシャルデータの利用状況を返します。

リクエスト例

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

レスポンス

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

利用状況のフィールド

cycle_session_limit
現在のサイクルで開始できるセッションの上限。上限がない場合は null。
cycle_sessions_used
現在のサイクルで開始したセッション数。
cycle_sessions_remaining
現在のサイクルで残っているセッション数。上限がない場合は null。
running_session_limit
同時に実行できるセッションの上限。
running_sessions_used
現在実行中として数えられているセッション数。
running_sessions_remaining
その上限までの空き枠。起動時にはほかのチェックも行われます。
cycle_start
現在のサイクルの開始日 (YYYY-MM-DD)。
residential_cycle_mb_limit
サイクルごとに含まれるレジデンシャルデータ (MB)。データ枠がない場合は null。
residential_bytes_used_cycle
現在のサイクルで使ったレジデンシャルデータ (バイト)。
pools
合計の内訳となるサブスクリプションごとの同じメーター。subscription_id、plan_id、plan_name を含みます。

利用状況のみ

GET/v8/user/quota

GET /user/api と同じ利用状況のフィールドを返します。連絡先メールアドレスとプログラムからのアクセスの有無は含みません。

リクエスト例

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

レスポンス

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