Create a browser session

POST/browsers

Create a new browser session from within an action.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Parameters for creating a browser session.

invocation_id?string

action invocation ID

name?string

Optional human-readable name for the browser session, used to find it later in the dashboard. Must be unique among active sessions within the project. Can be changed later via PATCH /browsers/{id_or_name}.

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

Length1 <= length <= 255

tags?

Optional user-defined key-value tags for the browser session, used to find and group sessions later. Can be changed later via PATCH /browsers/{id_or_name}. Up to 50 pairs.

Propertiesproperties <= 50

stealth?boolean

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

headless?boolean

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

gpu?boolean

If true, enables GPU acceleration for the browser session. Requires Start-Up or Enterprise plan and headless=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.

Range10 <= value <= 259200

profile?|

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.

extensions?array<|>

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

Itemsitems <= 20

proxy_id?string

Optional proxy to associate to the browser session. Must reference a proxy in the same project as the browser session.

viewport?

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).

kiosk_mode?boolean

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

start_url?string

Optional URL to open when the browser session is created. Navigation is best-effort, so navigation failures do not prevent the session from being created.

chrome_policy?

Custom Chrome enterprise policy overrides applied to this browser session. Keys are Chrome enterprise policy names; values must match their expected types. Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See https://chromeenterprise.google/policies/

telemetry?

Telemetry configuration for the browser session. Set enabled to true to start capture using VM defaults, or provide browser category settings. If omitted, null, set to an empty object ({}), set to enabled: false without browser category settings, or all four categories are explicitly disabled, capture is not started.

Response

application/json

Successful response

created_at*string

When the browser session was created.

Formatdate-time

cdp_ws_url*string

Websocket URL for Chrome DevTools Protocol connections to the browser session

webdriver_ws_url*string

Websocket URL for WebDriver BiDi connections to the browser session

browser_live_view_url?string

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

base_url?string

Metro-API HTTP base URL for this browser session.

headless*boolean

Whether the browser session is running in headless mode.

stealth*boolean

Whether the browser session is running in stealth mode.

gpu?boolean

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

session_id*string

Unique identifier for the browser session

name?string

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

timeout_seconds*integer

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

profile?

Browser profile metadata.

proxy_id?string

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

pool?

Browser pool this session was acquired from, if any.

viewport?

kiosk_mode?boolean

Whether the browser session is running in kiosk mode.

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.

chrome_policy?

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

tags?

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

Propertiesproperties <= 50

deleted_at?string

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

Formatdate-time

usage?

Session usage metrics.

telemetry?

Active telemetry configuration for the session, if any.

curl -X POST "https://example.com/browsers" \  -H "Content-Type: application/json" \  -d '{}'

{  "created_at": "2019-08-24T14:15:22Z",  "cdp_ws_url": "string",  "webdriver_ws_url": "string",  "browser_live_view_url": "string",  "base_url": "string",  "headless": true,  "stealth": true,  "gpu": true,  "session_id": "string",  "name": "string",  "timeout_seconds": 0,  "profile": {    "id": "string",    "name": "string",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z",    "last_used_at": "2019-08-24T14:15:22Z"  },  "proxy_id": "string",  "pool": {    "id": "string",    "name": "string"  },  "viewport": {    "width": 1,    "height": 1,    "refresh_rate": 1  },  "kiosk_mode": true,  "start_url": "string",  "chrome_policy": {},  "tags": {    "property1": "string",    "property2": "string"  },  "deleted_at": "2019-08-24T14:15:22Z",  "usage": {    "uptime_ms": 0  },  "telemetry": {    "browser": {      "console": {        "enabled": true      },      "page": {        "enabled": true      },      "interaction": {        "enabled": true      },      "network": {        "enabled": true      },      "control": {        "enabled": true      },      "connection": {        "enabled": true      },      "system": {        "enabled": true      },      "screenshot": {        "enabled": true      },      "captcha": {        "enabled": true      }    }  }}

{  "code": "string",  "message": "string",  "details": [    {      "code": "string",      "message": "string"    }  ],  "inner_error": {    "code": "string",    "message": "string"  }}

{  "code": "string",  "message": "string",  "details": [    {      "code": "string",      "message": "string"    }  ],  "inner_error": {    "code": "string",    "message": "string"  }}

{  "code": "string",  "message": "string",  "details": [    {      "code": "string",      "message": "string"    }  ],  "inner_error": {    "code": "string",    "message": "string"  }}

{  "code": "string",  "message": "string",  "details": [    {      "code": "string",      "message": "string"    }  ],  "inner_error": {    "code": "string",    "message": "string"  }}

{  "code": "string",  "message": "string",  "details": [    {      "code": "string",      "message": "string"    }  ],  "inner_error": {    "code": "string",    "message": "string"  }}

{  "code": "string",  "message": "string",  "details": [    {      "code": "string",      "message": "string"    }  ],  "inner_error": {    "code": "string",    "message": "string"  }}

{  "code": "string",  "message": "string",  "details": [    {      "code": "string",      "message": "string"    }  ],  "inner_error": {    "code": "string",    "message": "string"  }}