List browser sessions

curl --request GET \
  --url https://api.onkernel.com/browsers \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.onkernel.com/browsers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.onkernel.com/browsers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.onkernel.com/browsers"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.onkernel.com/browsers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

[
  {
    "cdp_ws_url": "wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/cdp?jwt=eyJ0eXAi...",
    "created_at": "2023-11-07T05:31:56Z",
    "headless": false,
    "session_id": "htzv5orfit78e1m2biiifpbv",
    "stealth": false,
    "timeout_seconds": 123,
    "webdriver_ws_url": "wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/webdriver/session?jwt=eyJ0eXAi...",
    "base_url": "https://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/kernel",
    "browser_live_view_url": "https://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/live?jwt=eyJ0eXAi...",
    "chrome_policy": {},
    "deleted_at": "2023-11-07T05:31:56Z",
    "gpu": false,
    "kiosk_mode": false,
    "name": "checkout-flow-1",
    "network": {
      "private_hosts": [
        "*.example.ts.net",
        "100.64.0.0/10"
      ]
    },
    "pool": {
      "id": "<string>",
      "name": "<string>"
    },
    "profile": {
      "created_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "last_used_at": "2023-11-07T05:31:56Z",
      "name": "<string>",
      "updated_at": "2023-11-07T05:31:56Z"
    },
    "profile_save_changes": true,
    "proxy": {
      "id": "<string>",
      "name": "<string>"
    },
    "proxy_id": "<string>",
    "start_url": "https://example.com",
    "tags": {
      "env": "staging",
      "team": "backend"
    },
    "telemetry": {
      "browser": {
        "captcha": {
          "enabled": true
        },
        "connection": {
          "enabled": true
        },
        "console": {
          "enabled": true
        },
        "control": {
          "enabled": true
        },
        "interaction": {
          "enabled": true
        },
        "network": {
          "enabled": true
        },
        "page": {
          "enabled": true
        },
        "screenshot": {
          "enabled": true
        },
        "system": {
          "enabled": true
        }
      },
      "export": {
        "otlp": {
          "destination": "<string>",
          "enabled": true
        }
      }
    },
    "usage": {
      "uptime_ms": 123
    },
    "viewport": {
      "height": 800,
      "width": 1280,
      "refresh_rate": 60
    }
  }
]

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

GET

browsers

List browser sessions

curl --request GET \
  --url https://api.onkernel.com/browsers \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.onkernel.com/browsers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.onkernel.com/browsers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.onkernel.com/browsers"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.onkernel.com/browsers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

[
  {
    "cdp_ws_url": "wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/cdp?jwt=eyJ0eXAi...",
    "created_at": "2023-11-07T05:31:56Z",
    "headless": false,
    "session_id": "htzv5orfit78e1m2biiifpbv",
    "stealth": false,
    "timeout_seconds": 123,
    "webdriver_ws_url": "wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/webdriver/session?jwt=eyJ0eXAi...",
    "base_url": "https://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/kernel",
    "browser_live_view_url": "https://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/live?jwt=eyJ0eXAi...",
    "chrome_policy": {},
    "deleted_at": "2023-11-07T05:31:56Z",
    "gpu": false,
    "kiosk_mode": false,
    "name": "checkout-flow-1",
    "network": {
      "private_hosts": [
        "*.example.ts.net",
        "100.64.0.0/10"
      ]
    },
    "pool": {
      "id": "<string>",
      "name": "<string>"
    },
    "profile": {
      "created_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "last_used_at": "2023-11-07T05:31:56Z",
      "name": "<string>",
      "updated_at": "2023-11-07T05:31:56Z"
    },
    "profile_save_changes": true,
    "proxy": {
      "id": "<string>",
      "name": "<string>"
    },
    "proxy_id": "<string>",
    "start_url": "https://example.com",
    "tags": {
      "env": "staging",
      "team": "backend"
    },
    "telemetry": {
      "browser": {
        "captcha": {
          "enabled": true
        },
        "connection": {
          "enabled": true
        },
        "console": {
          "enabled": true
        },
        "control": {
          "enabled": true
        },
        "interaction": {
          "enabled": true
        },
        "network": {
          "enabled": true
        },
        "page": {
          "enabled": true
        },
        "screenshot": {
          "enabled": true
        },
        "system": {
          "enabled": true
        }
      },
      "export": {
        "otlp": {
          "destination": "<string>",
          "enabled": true
        }
      }
    },
    "usage": {
      "uptime_ms": 123
    },
    "viewport": {
      "height": 800,
      "width": 1280,
      "refresh_rate": 60
    }
  }
]

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

status

enum<string>

default:active

Filter sessions by status. "active" returns only active sessions (default), "deleted" returns only soft-deleted sessions, "all" returns both.

Available options:

active,

deleted,

all

include_deleted

boolean

default:false

Deprecated: Use status=all instead. When true, includes soft-deleted browser sessions in the results alongside active sessions.

limit

integer

default:20

Maximum number of results to return. Defaults to 20, maximum 100.

Required range: 1 <= x <= 100

offset

integer

default:0

Number of results to skip. Defaults to 0.

Required range: x >= 0

query

string

Search browsers by name, session ID, profile name or ID, proxy ID, or pool name.

Response

List of browsers

cdp_ws_url

string

required

Websocket URL for Chrome DevTools Protocol connections to the browser session

Example:

"wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/cdp?jwt=eyJ0eXAi..."

created_at

string<date-time>

required

When the browser session was created.

headless

boolean

required

Whether the browser session is running in headless mode.

Example:

false

region

enum<string>

required

Geographic region of the browser session. Fixed once the session is created.

Available options:

us-east,

eu-west

session_id

string

required

Unique identifier for the browser session

Example:

"htzv5orfit78e1m2biiifpbv"

stealth

boolean

required

Whether the browser session is running in stealth mode.

Example:

false

timeout_seconds

integer

required

The number of seconds of inactivity before the browser session is terminated.

webdriver_ws_url

string

required

Websocket URL for WebDriver BiDi connections to the browser session

Example:

"wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/webdriver/session?jwt=eyJ0eXAi..."

base_url

string

Metro-API HTTP base URL for this browser session.

Example:

"https://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/kernel"

browser_live_view_url

string

Remote URL for live viewing the browser session. Only available for non-headless browsers.

Example:

"https://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/live?jwt=eyJ0eXAi..."

chrome_policy

object

Custom Chrome enterprise policy overrides that were applied to this browser session, if any. Echoed back for verification. Keys are Chrome enterprise policy names.

deleted_at

string<date-time>

When the browser session was soft-deleted. Only present for deleted sessions.

gpu

boolean

Whether GPU acceleration is enabled for the browser session (only supported for headful sessions).

Example:

false

kiosk_mode

boolean

Whether the browser session is running in kiosk mode.

Example:

false

name

string

Human-readable name of the browser session, if one was set at creation.

Example:

"checkout-flow-1"

network

object

Network configuration the session was created with, if any. Omitted when the session has no network configuration.

Show child attributes

pool

object

Browser pool this session was acquired from, if any.

Show child attributes

profile

object

Browser profile metadata.

Show child attributes

profile_save_changes

boolean

Whether changes made during this browser session are saved back to its profile when the session ends. Omitted when no profile is attached.

proxy

object

Resolved proxy configuration for this browser session.

Option 1
Option 2
Option 3

Show child attributes

proxy_id

string

deprecated

ID of the proxy associated with this browser session, if any. Deprecated in favor of proxy.

start_url

string

URL the session was asked to navigate to on creation, if any. Recorded for debugging. Navigation is fire-and-forget — the URL is dispatched to the browser without waiting for it to load, and any errors (DNS failure, bad status, timeout) are silently dropped. Captures what was requested, not what the browser actually loaded.

Example:

"https://example.com"

Apps

Audit Logs

Managed Auth

Authentication

Browser Pools

Browsers

Browser Computer Controls

Browser Filesystem

Browser Logs

Browser Playwright

Browser Processes

Browser Replays

Browser Telemetry

Deployments

Extensions

Invocations

API Keys

Organization

Projects

Profiles

Proxies

List browser sessions

Authorizations

Query Parameters

Response