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

Acquire a browser from the pool

cURL

curl --request POST \
  --url https://api.onkernel.com/browser_pools/{id_or_name}/acquire \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "acquire_timeout_seconds": 123,
  "name": "checkout-flow-1",
  "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
      }
    },
    "enabled": true,
    "export": {
      "otlp": {
        "destination": {
          "id": "<string>",
          "name": "<string>"
        },
        "enabled": true
      }
    }
  }
}
'

200

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

Authorizations

Authorization · string · header · required

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

Path Parameters

id_or_name · string · required

Browser pool ID or name

Body

application/json

Request body for acquiring a browser from the pool.

acquire_timeout_seconds · integer

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.

name · string

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.

Required string length: 1 - 255

Pattern: ^[a-zA-Z0-9._-]{1,255}$

Example:

"checkout-flow-1"

start_url · string

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.

Example:

"https://example.com"

tags · object

Optional user-defined key-value tags for the acquired browser session, used to find and group sessions later. Applies to this lease only and are cleared when the browser is released back to the pool. Up to 50 pairs.

Show child attributes

Example:

{ "env": "staging", "team": "backend" }

telemetry · object | null

Telemetry override for the acquired browser, applied to this lease only. Merges onto the browser's current (pool-inherited) telemetry using the same per-category semantics as PATCH /browsers: provided categories override the current configuration, omitted categories are inherited. Set enabled to true to resolve the config fresh from the default set, or enabled to false to stop capture. When the browser is released back to the pool with reuse, its telemetry is reset to the pool's baseline, so the override does not carry over to the next lease.

Show child attributes

Response

200

application/json

Browser acquired successfully

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"

tags · object

User-defined key-value tags that were set on this browser session, if any. Echoed back when present.

Show child attributes

Example:

{ "env": "staging", "team": "backend" }

telemetry · object | null

Active telemetry configuration for the session, if any.

Show child attributes

usage · object

Session usage metrics.

Show child attributes

viewport · object

Initial browser window size in pixels with optional refresh rate. If omitted, image defaults apply (1920x1080@25). For GPU images, the default is 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60, 768x1024@60, 390x844@60. For GPU images, recommended presets use one of these resolutions with refresh rates 60, 30, 25, or 10: 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. Viewports outside this list may exhibit unstable live view or recording behavior. If refresh_rate is not provided, it will be automatically determined based on the resolution (higher resolutions use lower refresh rates to keep bandwidth reasonable).

Show child attributes