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

Different from GraphQL Sessions Query

This sessions API is for creating and managing persistent browser sessions via REST endpoints. This should not be confused with the GraphQL sessions query, which is used for monitoring and retrieving information about currently running sessions.

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

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"
    ]
  }'

Javascript

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();

Python

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']}")

Java

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();
        }
    }
}

C#

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

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

Javascript

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();

Python

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)

Java

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();
        }
    }
}

C#

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"
}]