/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
- Javascript
- Python
- Java
- C#
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"
]
}'
const TOKEN = "YOUR_API_TOKEN_HERE";
const url = "https://production-sfo.browserless.io/session";
const createSession = async () => {
const sessionConfig = {
ttl: 300000, // 5 minutes
stealth: true,
headless: false,
args: [
"--no-sandbox",
"--disable-dev-shm-usage"
]
};
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${TOKEN}`
},
body: JSON.stringify(sessionConfig)
});
const session = await response.json();
console.log("Session created:", session.id);
console.log("Connect URL:", session.connect);
return session;
};
createSession();
import requests
import json
TOKEN = "YOUR_API_TOKEN_HERE"
url = "https://production-sfo.browserless.io/session"
session_config = {
"ttl": 300000, # 5 minutes
"stealth": True,
"headless": False,
"args": [
"--no-sandbox",
"--disable-dev-shm-usage"
]
}
response = requests.post(
url,
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {TOKEN}"
},
json=session_config
)
session = response.json()
print(f"Session created: {session['id']}")
print(f"Connect URL: {session['connect']}")
import java.io.*;
import java.net.URI;
import java.net.http.*;
public class CreateSession {
public static void main(String[] args) {
String TOKEN = "YOUR_API_TOKEN_HERE";
String url = "https://production-sfo.browserless.io/session";
String requestBody = """
{
"ttl": 300000,
"stealth": true,
"headless": false,
"args": [
"--no-sandbox",
"--disable-dev-shm-usage"
]
}
""";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.header("Authorization", "Bearer " + TOKEN)
.POST(HttpRequest.BodyPublishers.ofString(requestBody))
.build();
try {
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("Response: " + response.body());
} catch (Exception e) {
e.printStackTrace();
}
}
}
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main(string[] args) {
string TOKEN = "YOUR_API_TOKEN_HERE";
string url = "https://production-sfo.browserless.io/session";
var sessionConfig = @"{
""ttl"": 300000,
""stealth"": true,
""headless"": false,
""args"": [
""--no-sandbox"",
""--disable-dev-shm-usage""
]
}";
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {TOKEN}");
var content = new StringContent(sessionConfig, Encoding.UTF8, "application/json");
try {
var response = await client.PostAsync(url, content);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine("Response: " + result);
} catch (Exception ex) {
Console.WriteLine($"Error: {ex.Message}");
}
}
}
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
Parameter | Type | Default | Description |
---|---|---|---|
ttl | number | 300000 | Time-to-live in ms (session timeout) |
stealth | boolean | false | Enable stealth mode to avoid detection |
headless | boolean | true | Run browser in headless mode |
args | string[] | [] | Additional Chrome launch arguments |
proxy | object | null | Proxy 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
- Javascript
- Python
- Java
- C#
curl -X GET \
https://production-sfo.browserless.io/sessions?token=YOUR_API_TOKEN_HERE
const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/sessions?token=${TOKEN}`;
const fetchSessions = async () => {
const response = await fetch(url, {
method: 'GET'
});
const result = await response.json();
console.log(result);
};
fetchSessions();
import requests
TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/sessions?token={TOKEN}"
response = requests.get(url)
result = response.json()
print(result)
import java.io.*;
import java.net.URI;
import java.net.http.*;
public class FetchSessions {
public static void main(String[] args) {
String TOKEN = "YOUR_API_TOKEN_HERE";
String url = "https://production-sfo.browserless.io/sessions?token=" + TOKEN;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.GET()
.build();
try {
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("Response: " + response.body());
} catch (Exception e) {
e.printStackTrace();
}
}
}
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program {
static async Task Main(string[] args) {
string TOKEN = "YOUR_API_TOKEN_HERE";
string url = $"https://production-sfo.browserless.io/sessions?token={TOKEN}";
using var client = new HttpClient();
try {
var response = await client.GetAsync(url);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine("Response: " + result);
} catch (Exception ex) {
Console.WriteLine($"Error: {ex.Message}");
}
}
}
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"
}]