API ReferenceAPI v2Sessions

Create Session

Create a new session with a new task.

Authentication

X-Browser-Use-API-Keystring
API Key authentication via header

Request

This endpoint expects an object.
profileIdstring or nullOptionalformat: "uuid"
The ID of the profile to use for the session
proxyCountryCodeenum or nullOptional
Country code for proxy location.
startUrlstring or nullOptional
URL to navigate to when the session starts.
browserScreenWidthinteger or nullOptional320-6144
Custom screen width in pixels for the browser.
browserScreenHeightinteger or nullOptional320-3456
Custom screen height in pixels for the browser.
persistMemorybooleanOptionalDefaults to true

If True (default), tasks in this session share memory and history with each other, allowing follow-up tasks to continue from previous context. If False, each task runs as a standalone task without any previous task context.

keepAlivebooleanOptionalDefaults to true

If True (default), the browser session stays alive after tasks complete, allowing follow-up tasks. If False, the session is closed immediately after task completion. Set to False for simple one-off tasks to reduce session idle time.

customProxyobject or nullOptional
Custom proxy settings to use for the session. If not provided, our proxies will be used. Custom proxies are only available for Business and Scaleup subscribers.

Response

Successful Response
idstringformat: "uuid"
Unique identifier for the session
statusenum

Current status of the session (active/stopped)

Allowed values:
startedAtdatetime
Timestamp when the session was created and started
persistMemoryboolean
Whether tasks in this session share memory and history with each other
keepAliveboolean
Whether the browser session stays alive after tasks complete
liveUrlstring or null

URL where the browser can be viewed live in real-time

finishedAtdatetime or null

Timestamp when the session was stopped (None if still active)

proxyUsedMbstring or nullformat: "^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$"Defaults to 0
Amount of proxy data used in MB
proxyCoststring or nullformat: "^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$"Defaults to 0
Cost of proxy usage in USD

Errors