Create a browser session

Create a new browser session from within an action.

POST /browsers

JavaScript

JavaScript

import Kernel from '@onkernel/sdk';

const client = new Kernel({
  apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted
});

const browser = await client.browsers.create();

console.log(browser.session_id);

200

{
  "created_at": "2023-11-07T05:31:56Z",
  "cdp_ws_url": "wss://api.onkernel.com/browser/cdp?jwt=eyJ0eXAi...",
  "headless": false,
  "stealth": false,
  "session_id": "htzv5orfit78e1m2biiifpbv",
  "timeout_seconds": 123,
  "browser_live_view_url": "https://api.onkernel.com/browser/remote?jwt=eyJ0eXAi...",
  "persistence": {
    "id": "my-awesome-browser-for-user-1234"
  },
  "profile": {
    "id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "name": "<string>",
    "updated_at": "2023-11-07T05:31:56Z",
    "last_used_at": "2023-11-07T05:31:56Z"
  },
  "proxy_id": "<string>",
  "viewport": {
    "width": 1280,
    "height": 800,
    "refresh_rate": 60
  },
  "kiosk_mode": false,
  "deleted_at": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization · string · header · required

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

Body

application/json

Parameters for creating a browser session.

invocation_id · string

action invocation ID

Example:

"rr33xuugxj9h0bkf1rdt2bet"

persistence · object · deprecated

DEPRECATED: Use timeout_seconds (up to 72 hours) and Profiles instead.

Show child attributes

stealth · boolean

If true, launches the browser in stealth mode to reduce detection by anti-bot mechanisms.

Example:

true

headless · boolean

If true, launches the browser using a headless image (no VNC/GUI). Defaults to false.

Example:

false

timeout_seconds · integer

The number of seconds of inactivity before the browser session is terminated. Activity includes CDP connections and live view connections. Defaults to 60 seconds. Minimum allowed is 10 seconds. Maximum allowed is 259200 (72 hours). We check for inactivity every 5 seconds, so the actual timeout behavior you will see is +/- 5 seconds around the specified value.

Required range: 10 <= x <= 259200

profile · object

Profile selection for the browser session. Provide either id or name. If specified, the matching profile will be loaded into the browser session. Profiles must be created beforehand.

Option 1

Option 2

Show child attributes

extensions · object[]

List of browser extensions to load into the session. Provide each by id or name.

Maximum array length: 20

Extension selection for the browser session. Provide either id or name of an extension uploaded to Kernel.

Option 1

Option 2

Show child attributes

proxy_id · string

Optional proxy to associate to the browser session. Must reference a proxy belonging to the caller's org.

viewport · object

Initial browser window size in pixels with optional refresh rate. If omitted, image defaults apply (1920x1080@25). Only specific viewport configurations are supported. The server will reject unsupported combinations. Supported resolutions are: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1024x768@60, 1200x800@60 If refresh_rate is not provided, it will be automatically determined from the width and height if they match a supported configuration exactly. Note: Higher resolutions may affect the responsiveness of live view browser

Show child attributes

kiosk_mode · boolean

If true, launches the browser in kiosk mode to hide address bar and tabs in live view.

Example:

true

Response

200

application/json

Successful response

created_at · string<date-time> · required

When the browser session was created.

cdp_ws_url · string · required

Websocket URL for Chrome DevTools Protocol connections to the browser session

Example:

"wss://api.onkernel.com/browser/cdp?jwt=eyJ0eXAi..."

headless · boolean · required

Whether the browser session is running in headless mode.

Example:

false

stealth · boolean · required

Whether the browser session is running in stealth mode.

Example:

false

session_id · string · required

Unique identifier for the browser session

Example:

"htzv5orfit78e1m2biiifpbv"

timeout_seconds · integer · required

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

browser_live_view_url · string

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

Example:

"https://api.onkernel.com/browser/remote?jwt=eyJ0eXAi..."

persistence · object · deprecated

DEPRECATED: Use timeout_seconds (up to 72 hours) and Profiles instead.

Show child attributes

profile · object

Browser profile metadata.

Show child attributes

proxy_id · string

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

viewport · object

Initial browser window size in pixels with optional refresh rate. If omitted, image defaults apply (1920x1080@25). Only specific viewport configurations are supported. The server will reject unsupported combinations. Supported resolutions are: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1024x768@60, 1200x800@60 If refresh_rate is not provided, it will be automatically determined from the width and height if they match a supported configuration exactly. Note: Higher resolutions may affect the responsiveness of live view browser

Show child attributes

kiosk_mode · boolean

Whether the browser session is running in kiosk mode.

Example:

false

deleted_at · string<date-time>

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