Skip to main content
Use manage_browsers when your agent needs one live browser session to inspect, automate, or debug web state. A created browser runs in an isolated VM and can use profiles, proxies, viewports, extensions, Chrome policy overrides, telemetry, start URLs, and SSH tunneling. For repeated browser work with the same configuration, use Manage Browser Pools instead. Pools reduce startup latency when your agent needs many similar sessions.

​
Actions

ActionDescription
createLaunch a new browser session.
updateChange supported session settings.
listList existing sessions.
getRetrieve details about a specific session.
deleteTerminate a session.
  1. Call list before creating a browser if an existing session might already be active.
  2. Call create with the browser configuration the task needs.
  3. Use computer_action, execute_playwright_code, browser_curl, or exec_command with the returned session_id.
  4. Call update only for session settings that can change after launch, such as profile, proxy, viewport, or telemetry.
  5. Call delete when the task is done. If save_profile_changes is enabled, deleting the browser saves changes back to the selected profile.

​
Parameters

ParameterDescription
actionOperation to perform: create, update, list, get, or delete. Required.
session_idBrowser session ID. Required for update, get, and delete.
start_url(create) URL to open when the browser is created. Navigation is best effort.
chrome_policy(create) Chrome enterprise policy overrides. The API blocks Kernel-managed policies such as extensions, proxy, CDP, and automation. Empty objects are ignored.
headless(create) Launch without GUI. Faster but no live view.
gpu(create) Enable GPU acceleration. Requires headless=false and a Start-Up or Enterprise plan. See GPU Acceleration.
stealth(create) Avoid bot detection. Recommended for scraping.
kiosk_mode(create) Hide address bar/tabs in live view.
profile_id / profile_name(create, update) Profile to load saved cookies and logins. Use one, not both.
save_profile_changes(create, update) Save session changes back to the profile on close.
proxy_id(create, update) Proxy ID for traffic routing.
clear_proxy(update) Remove the current proxy from the browser session.
disable_default_proxy(update) For stealth browsers, connect directly instead of using the default stealth proxy.
extension_id / extension_name(create) Extension to load.
viewport_width / viewport_height(create, update) Window size in pixels. Set both values together.
viewport_refresh_rate(create, update) Display refresh rate in Hz.
viewport_force(update) Force viewport changes even when live view or recording is active.
timeout_seconds(create) Inactivity timeout in seconds (max 259200 = 72h). Default 60.
local_forward(create) SSH local forwarding (localport:host:remoteport).
remote_forward(create) SSH remote forwarding (remoteport:host:localport). Use to expose a local dev server to the browser.
status(list) Filter by status: active, deleted, or all. Default active.
limit(list) Max results per page. Must be 1-100.
offset(list) Pagination offset. Must be 0 or greater.
telemetry_enabled(create, update) Enable telemetry with VM defaults, or disable telemetry when false.
telemetry_console(create, update) Enable or disable console telemetry.
telemetry_network(create, update) Enable or disable network telemetry.
telemetry_page(create, update) Enable or disable page lifecycle telemetry.
telemetry_interaction(create, update) Enable or disable user interaction telemetry.

​
Response behavior

create and update return structured JSON with browser and next_actions. If you request SSH forwarding, the response includes ssh_port_forwarding with the CLI command, prerequisites, and the URL to use after the tunnel is running. list returns compact browser summaries and omits routine connection details such as cdp_ws_url. Use get with session_id when your agent needs full details.

​
Create a browser

{
  "action": "create",
  "stealth": true,
  "proxy_id": "proxy_residential_us",
  "profile_name": "work-accounts",
  "save_profile_changes": true,
  "start_url": "https://app.example.com/dashboard",
  "viewport_width": 1440,
  "viewport_height": 900,
  "telemetry_network": true,
  "timeout_seconds": 3600
}

​
Update a browser

{
  "action": "update",
  "session_id": "browser_2vDb5kRmZ4nP8xQ1cA7",
  "viewport_width": 1280,
  "viewport_height": 720,
  "viewport_force": true,
  "clear_proxy": true
}