For AI agents: a documentation index is available at /llms.txt
Skip to main content

/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

    ttlnumberrequired

    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.

    processKeepAlivenumber

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

    stealthboolean

    Whether or not to enable advanced stealth mode. Defaults to false.

    blockAdsboolean

    Whether or not to enable ad-blocking. Defaults to false.

    blockAdsIncludestring

    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.

    headlessboolean

    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.

    deviceScaleFactornumber
    hasTouchboolean
    heightnumberrequired
    isLandscapeboolean
    isMobileboolean
    widthnumberrequired
    argsstring[]

    An array of command-line arguments to pass to the browser. Defaults to an empty array.

    browserstring

    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]

    urlstring

    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.

    typestring

    The type of proxy to use: 'residential' or 'datacenter'.

    Possible values: [datacenter, residential]

    stickyboolean

    Whether or not to use the same IP address for all proxied requests. Defaults to true

    countrystring

    The country to proxy through. Defaults to 'us' or United States

    citystring

    The city to proxy through.

    statestring

    The state to proxy through.

    presetstring

    Preset code for website-specific proxy configurations (e.g., 'px_gov01' for government sites)

    replayboolean

    Whether to enable session recording for replay. When true, the session will be recorded and can be replayed later.

    extensionsstring[]

    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.

    profilestring

    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.

    integrationIdstring

    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.

    property name*string
    allowedDomainsstring[]

    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[]
  • Array [
  • string
  • ]
  • labelstring

    An optional, caller-supplied label for the session. Stored on the session record for the caller's own bookkeeping; does not affect behavior.

Responses​

Schema
    idstringrequired

    The ID of the session

    connectstringrequired

    The fully-qualified URL to connect CDP-based libraries to the session

    ttlnumberrequired

    The total time of life in milliseconds

    stopstringrequired

    The fully qualified URL to stop and remove the session with a DELETE method.

    browserQLstringrequired

    The fully-qualified URL to run BrowserQL queries against the session

    cloudEndpointIdstringrequired

    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.

    routingBasestringrequired

    The routing base for this session, including its routing scheme and owner reference.

Was this page helpful?