Skip to main content

/sessions API

The sessions API allows you to gather information about the currently running sessions and is only available for dedicated and self-hosted accounts

You can check the full Open API schema here.

Creating a new session

You can create new sessions programmatically using a POST request to /session. This allows you to configure session parameters like timeout, stealth mode, and browser arguments:

curl -X POST \
https://production-sfo.browserless.io/session \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN_HERE" \
-d '{
"ttl": 300000,
"stealth": true,
"headless": false,
"args": [
"--no-sandbox",
"--disable-dev-shm-usage"
]
}'

Creating a session will return a response like:

{
"id": "session-123456",
"connect": "wss://production-sfo.browserless.io/session/session-123456?token=YOUR_API_TOKEN_HERE",
"ttl": 300000,
"stop": "https://production-sfo.browserless.io/session/session-123456?token=YOUR_API_TOKEN_HERE",
"browserQL": "https://production-sfo.browserless.io/session/session-123456/browserql?token=YOUR_API_TOKEN_HERE"
}

Session Configuration Options

ParameterTypeDefaultDescription
ttlnumber300000Time-to-live in ms (session timeout)
stealthbooleanfalseEnable stealth mode to avoid detection
headlessbooleantrueRun browser in headless mode
argsstring[][]Additional Chrome launch arguments
proxyobjectnullProxy configuration

For more detailed session management and persistence options, see the Session Management documentation.

Gathering information from your running sessions

To see information regarding the running sessions, simply issue a GET request to /sessions:

curl -X GET \
https://production-sfo.browserless.io/sessions?token=YOUR_API_TOKEN_HERE
warning

Remember that running this in the browser will expose your API key!

Running this request will result in an output like:

[{
"id": null,
"initialConnectURL": "wss://production-sfo.browserless.io/firefox/playwright/?token=YOUR_API_TOKEN_HERE",
"isTempDataDir": true,
"launchOptions": {},
"numbConnected": 1,
"routePath": ["/firefox/playwright", "/firefox/playwright"],
"startedOn": 1709584439748,
"ttl": 0,
"userDataDir": null,
"browser": "FirefoxPlaywright",
"browserId": "d9a8570a73666d79d79ac23f07cf8966",
"killURL": null,
"running": true,
"timeAliveMs": 10118,
"type": "browser"
}]