Sign in
latestOpenAPI 3.1.02026-08-22154287463.4 KB

858365328f92

Browser Pools

Acquire a browser from the pool

Long-polling endpoint to acquire a browser from the pool. Returns immediately when a browser is available, or returns 204 No Content when the poll times out. The client should retry the request to continue waiting for a browser. The acquired browser will use the pool's timeout_seconds for its idle timeout.

post/browser_pools/{id_or_name}/acquire

Path parameters

id_or_namestring required

Browser pool ID or name

Request body

acquire_timeout_secondsinteger

Maximum number of seconds to wait for a browser to be available. Defaults to the calculated time it would take to fill the pool at the currently configured fill rate.

namestring

Optional human-readable name for the acquired browser session, used to find it later in the dashboard. Must be unique among active sessions within the pool's project. Applies to this lease only and is cleared when the browser is released back to the pool.

start_urlstring

Optional URL to navigate the acquired browser to. Overrides the pool's start_url for this acquire only. Best-effort: failures to navigate do not fail the acquire.

tagsTags

User-defined key-value tags.

Example request

{
  "name": "checkout-flow-1",
  "start_url": "https://example.com",
  "tags": {
    "env": "staging",
    "team": "backend"
  }
}

Response

Browser acquired successfully

base_urlstring

Metro-API HTTP base URL for this browser session.

browser_live_view_urlstring

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

cdp_ws_urlstring required

Websocket URL for Chrome DevTools Protocol connections to the browser session

chrome_policyobject

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

created_atstring date-time required

When the browser session was created.

deleted_atstring date-time

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

gpuboolean

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

headlessboolean required

Whether the browser session is running in headless mode.

kiosk_modeboolean

Whether the browser session is running in kiosk mode.

memory'1GiB' | '2GiB' | '6GiB' | '8GiB' | '16GiB' required

Memory allocated to the browser session.

namestring

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

profile_save_changesboolean

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

proxy_idstring

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

region'us-east' | 'eu-west' required

Geographic region for hosting browser sessions or pools.

session_idstring required

Unique identifier for the browser session

start_urlstring

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.

stealthboolean required

Whether the browser session is running in stealth mode.

tagsTags

User-defined key-value tags.

timeout_secondsinteger required

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

webdriver_ws_urlstring required

Websocket URL for WebDriver BiDi connections to the browser session

Example response

{
  "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...",
  "cdp_ws_url": "wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/cdp?jwt=eyJ0eXAi...",
  "memory": "8GiB",
  "name": "checkout-flow-1",
  "network": {
    "private_hosts": [
      "*.example.ts.net",
      "100.64.0.0/10"
    ]
  },
  "session_id": "htzv5orfit78e1m2biiifpbv",
  "start_url": "https://example.com",
  "tags": {
    "env": "staging",
    "team": "backend"
  },
  "viewport": {
    "height": 800,
    "refresh_rate": 60,
    "width": 1280
  },
  "webdriver_ws_url": "wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/webdriver/session?jwt=eyJ0eXAi..."
}