/session
POST/session
Creates a new browser session with the specified parameters. The session can be used for persistent browser connections with well-defined lifetimes and reconnection semantics.
Request
Body
- Schema
- Example (auto)
- Array [
- ]
The time-to-live (TTL) for the session in milliseconds. Once reached, will be forcefully terminated and all files and processes will be cleaned up. Must be a non-negative number. Hosted Cloud accepts 0 as the plan's maximum retention and rejects values above that maximum.
An optional time, in milliseconds, to keep the underlying browser process alive after a connection to the session closes. If a connection happens within the keep-alive window, the browser process will remain running and the session can be reconnected to. If a connection happens after the keep-alive window has expired, a new browser process will be launched for the session, with the prior session data. Defaults to 0 (no keep-alive).
Whether or not to enable advanced stealth mode. Defaults to false.
Whether or not to enable ad-blocking. Defaults to false.
Restrict blockAds to a specific set of uBlock ruleset ids (comma-separated
list or JSON array). Only applies when blockAds is true. Fewer rulesets
means a faster browser launch under load; omit to load the full default set.
Whether the browser should be launched in headless mode.
Ignored if stealth is true, defaults to "true".
defaultViewport object
The default viewport for pages in non-stealth sessions. Ignored when
stealth is true or browser is "stealth". Takes precedence over the
connect URL's launch.defaultViewport, including after a browser restart.
An array of command-line arguments to pass to the browser. Defaults to an empty array.
The type of browser to use for the session. 'stealth' uses the Brave browser with advanced anti-detection. Defaults to 'chromium'.
Possible values: [chrome, chromium, stealth]
The underlying page URL you're attempting to automate. Some pages may required special handling in order to work correctly or unblock. This is not required, but can be useful or required for certain sites.
proxy object
Proxy Parameters for the session if desired. If not specified, the session will use the default network settings.
The type of proxy to use: 'residential' or 'datacenter'.
Possible values: [datacenter, residential]
Whether or not to use the same IP address for all proxied requests. Defaults to true
The country to proxy through. Defaults to 'us' or United States
The city to proxy through.
The state to proxy through.
Preset code for website-specific proxy configurations (e.g., 'px_gov01' for government sites)
Whether to enable session recording for replay. When true, the session will be recorded and can be replayed later.
An array of extension IDs to load into the browser session. Extensions must be previously uploaded to the browserless extension storage. This allows sessions to start with extensions pre-loaded without specifying them in launch arguments at connection time.
Optional name of an authentication profile to use as initial browser state. The profile's cookies, localStorage, and IndexedDB entries are injected via CDP before your code runs. sessionStorage is intentionally not restored — it is tab-scoped and stale values break OAuth/CSRF flows. Changes during the session do not affect the source profile.
Optional 1Password integration id (op_int_…) or label. Browserless.loadSecret can resolve credentials from this integration during the session. Validated at session creation; a missing or expired integration rejects the request.
credentials object
Maps caller aliases to 1Password op:// references, e.g. { "password": "op://Prod/GitHub/password" }. Reference strings are not secret; resolved values are never stored on the session.
Optionally narrows the integration's allowed-domain list for this session. Cannot widen it — the effective list is the intersection of the two.
credentialOrigins object
Optional alias → origins map. When set, each credential alias may only be filled on its own origins and unlisted aliases are refused.
property name* string[]
An optional, caller-supplied label for the session. Stored on the session record for the caller's own bookkeeping; does not affect behavior.
{
"ttl": 0,
"processKeepAlive": 0,
"stealth": true,
"blockAds": true,
"blockAdsInclude": "string",
"headless": true,
"defaultViewport": {
"deviceScaleFactor": 0,
"hasTouch": true,
"height": 0,
"isLandscape": true,
"isMobile": true,
"width": 0
},
"args": [
"string"
],
"browser": "chrome",
"url": "string",
"proxy": {
"type": "datacenter",
"sticky": true,
"country": "string",
"city": "string",
"state": "string",
"preset": "string"
},
"replay": true,
"extensions": [
"string"
],
"profile": "string",
"integrationId": "string",
"credentials": {},
"allowedDomains": [
"string"
],
"credentialOrigins": {},
"label": "string"
}
Responses
- 200
- 400
- 401
- 403
- 404
- 408
- 429
- 500
- 503
Schema
- Fields
- Example (auto)
The ID of the session
The fully-qualified URL to connect CDP-based libraries to the session
The total time of life in milliseconds
The fully qualified URL to stop and remove the session with a DELETE method.
The fully-qualified URL to run BrowserQL queries against the session
The legacy encrypted /e/ cloud endpoint ID; null unless the session URLs are /e/ URLs. Use the complete returned URLs or routingBase instead of constructing an /e/ URL.
The routing base for this session, including its routing scheme and owner reference.
{
"id": "string",
"connect": "string",
"ttl": 0,
"stop": "string",
"browserQL": "string",
"cloudEndpointId": "string",
"routingBase": "string"
}
The request contains errors or didn't properly encode content.
The request is missing, or contains bad, authorization credentials.
The request targets a destination that is not allowed.
Resource couldn't be found.
The request took has taken too long to process.
Too many requests are currently being processed.
An internal error occurred when handling the request.
Service is unavailable.