Persisting State

This guide covers creating a long-lived browser session with the Session REST API, running BQL queries against it, and cleaning up when you're done. It also covers session configuration options, how long state persists by plan, and best practices for managing sessions.

Prerequisites

• A Browserless API token from your account dashboard
• Familiarity with BQL reconnect

Comparison with BQL reconnect

The Session API and the BQL reconnect mutation both maintain browser continuity, but they work differently.

Feature	Session API + BQL	BQL Reconnect
Session Creation	Explicit via REST API	Implicit with first query
Lifecycle Control	Programmatic start/stop	Timeout-based only
State Management	Persistent across disconnections	Requires active connection
Proxy Configuration	Set once, applies to all queries	Per-query configuration

Persisting State Workflow

1. Create a Session

   POST to /session. Save the returned object. It contains the URLs you need for BQL queries and session cleanup.

   Stealth is optional

   browserQL is returned for all sessions and accepts queries whether or not stealth is enabled. The examples below pass stealth: true because it helps on bot-protected targets; omit it if you don't need it.

   JavaScript

   const response = await fetch(
     "https://production-sfo.browserless.io/session?token=YOUR_API_TOKEN_HERE",
     {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         ttl: 300000,
         stealth: true,
       }),
     }
   );
   
   if (!response.ok) {
     throw new Error(`Failed to create session: ${response.status}`);
   }
   
   const session = await response.json();
   console.log("Session created:", session.id);

   Python

   import requests
   
   response = requests.post(
       "https://production-sfo.browserless.io/session",
       params={"token": "YOUR_API_TOKEN_HERE"},
       json={
           "ttl": 300000,
           "stealth": True,
       },
   )
   
   response.raise_for_status()
   session = response.json()
   print("Session created:", session["id"])

   cURL

   curl -X POST "https://production-sfo.browserless.io/session?token=YOUR_API_TOKEN_HERE" \
     -H "Content-Type: application/json" \
     -d '{
       "ttl": 300000,
       "stealth": true
     }'

2. Run BQL Queries

   POST BQL mutations to session.browserQL. This is a fully-qualified URL returned for all sessions that inherits all session properties (proxy, stealth mode, etc.).

   JavaScript

   const query = `
     mutation SetDarkMode {
       goto(url: "https://docs.browserless.io/", waitUntil: networkIdle) {
         status
       }
       click(selector: "div.toggle_vylO.colorModeToggle_x44X > button") {
         time
       }
     }
   `;
   
   const bqlResponse = await fetch(session.browserQL, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({ query }),
   });
   
   const result = await bqlResponse.json();
   console.log("Dark mode toggled:", result.data);

   Python

   query = """
   mutation SetDarkMode {
     goto(url: "https://docs.browserless.io/", waitUntil: networkIdle) {
       status
     }
     click(selector: "div.toggle_vylO.colorModeToggle_x44X > button") {
       time
     }
   }
   """
   
   bql_response = requests.post(
       session["browserQL"],
       json={"query": query},
   )
   
   result = bql_response.json()
   print("Dark mode toggled:", result["data"])

3. Stop the Session

   You can POST to session.browserQL as many times as needed across multiple script runs. State persists across all of them. Only send a DELETE to session.stop when you want to permanently discard the session data. Sessions also expire automatically when their TTL elapses.

   JavaScript

   const stopResponse = await fetch(session.stop, { method: "DELETE" });
   
   if (stopResponse.ok) {
     console.log("Session stopped.");
   }

   Python

   stop_response = requests.delete(session["stop"])
   stop_response.raise_for_status()
   print("Session stopped.")

   cURL

   # Use the stop URL from the session creation response
   
   curl -X DELETE "SESSION_STOP_URL_HERE"

Complete Example

This example creates a session, toggles dark mode in one BQL query, then verifies the theme preference persists in a second query against the same session.

JavaScript

async function main() {
  // 1. Create a stealth session
  const response = await fetch(
    "https://production-sfo.browserless.io/session?token=YOUR_API_TOKEN_HERE",
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ ttl: 300000, stealth: true }),
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to create session: ${response.status}`);
  }

  const session = await response.json();
  console.log("Session created:", session.id);

  // 2. First query: navigate and toggle dark mode
  const toggleQuery = `
    mutation SetDarkMode {
      goto(url: "https://docs.browserless.io/", waitUntil: networkIdle) {
        status
      }
      click(selector: "div.toggle_vylO.colorModeToggle_x44X > button") {
        time
      }
    }
  `;

  const toggleResponse = await fetch(session.browserQL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: toggleQuery }),
  });

  const toggleResult = await toggleResponse.json();
  console.log("Dark mode toggled:", toggleResult.data.click.time);

  // 3. Second query: verify theme persists (reuse same session.browserQL URL)
  const verifyQuery = `
    mutation VerifyTheme {
      goto(url: "https://docs.browserless.io/", waitUntil: networkIdle) {
        status
      }
      theme: evaluate(content: "return localStorage.getItem('theme');") {
        value
      }
    }
  `;

  const verifyResponse = await fetch(session.browserQL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: verifyQuery }),
  });

  const verifyResult = await verifyResponse.json();
  console.log("Theme persisted:", verifyResult.data.theme.value);

  // 4. Clean up
  await fetch(session.stop, { method: "DELETE" });
  console.log("Session stopped.");
}

main().catch(console.error);

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"

# 1. Create a stealth session
response = requests.post(
    "https://production-sfo.browserless.io/session",
    params={"token": TOKEN},
    json={"ttl": 300000, "stealth": True},
)
response.raise_for_status()
session = response.json()
print("Session created:", session["id"])

# 2. First query: navigate and toggle dark mode
toggle_query = """
mutation SetDarkMode {
  goto(url: "https://docs.browserless.io/", waitUntil: networkIdle) {
    status
  }
  click(selector: "div.toggle_vylO.colorModeToggle_x44X > button") {
    time
  }
}
"""

toggle_response = requests.post(
    session["browserQL"],
    json={"query": toggle_query},
)
toggle_result = toggle_response.json()
print("Dark mode toggled:", toggle_result["data"]["click"]["time"])

# 3. Second query: verify theme persists (reuse same session.browserQL URL)
verify_query = """
mutation VerifyTheme {
  goto(url: "https://docs.browserless.io/", waitUntil: networkIdle) {
    status
  }
  theme: evaluate(content: "return localStorage.getItem('theme');") {
    value
  }
}
"""

verify_response = requests.post(
    session["browserQL"],
    json={"query": verify_query},
)
verify_result = verify_response.json()
print("Theme persisted:", verify_result["data"]["theme"]["value"])

# 4. Clean up
requests.delete(session["stop"])
print("Session stopped.")

Session Response Schema

A successful POST /session returns a JSON object with these fields:

Property	Type	Description
id	string	Unique session identifier
connect	string	WebSocket URL for CDP-based libraries (Puppeteer, Playwright). Token is pre-embedded.
browserQL	string	URL for running BQL queries against this session. Returned for all sessions. Token is pre-embedded.
stop	string	URL for session termination via DELETE request. Token is pre-embedded.
ttl	number	Session time-to-live in milliseconds
cloudEndpointId	string | null	Encrypted cloud endpoint ID for the session. Present on Browserless Cloud, null when self-hosted.

Persisted Session Data Duration

Session data (cookies, localStorage, cache) persists for the duration of the session TTL, up to the plan maximum:

Plan	Maximum Session Lifetime
Free	1 day
Prototyping	7 days
Starter	30 days
Scale	90 days
Enterprise	Custom

You can also limit persistence duration by passing a lower ttl value to the session API.

Session Configuration Options

All session configuration options apply to both WebSocket connections and BQL queries:

Parameter	Type	Default	Description
ttl	number	required	Time-to-live in milliseconds. Max varies by plan.
stealth	boolean	false	Enables stealth mode for bot-protected targets. Optional; BQL queries work without it.
headless	boolean	false	Run browser in headless mode. An omitted value resolves to false, so a session launches headful unless you pass true. Ignored when stealth is true.
browser	string	'chromium'	Browser type: 'chromium', 'chrome', or 'stealth'. The 'stealth' browser cannot be combined with the stealth property.
blockAds	boolean	false	Enable ad blocking.
args	string[]	[]	Additional Chrome launch arguments.
proxy	object	null	Proxy configuration. When set, applies to all BQL queries and WebSocket connections for this session. See proxy docs for the full configuration shape.

Best Practices

1. Store session URLs together. Save session.id, session.browserQL, and session.stop as a unit after session creation. You need all three for queries, cleanup, and debugging.

2. Delete sessions when done. Send a DELETE to session.stop when your workflow completes. Relying on TTL expiry alone wastes resources and can hit session limits.

3. Handle expired sessions. If a POST to session.browserQL returns a non-2xx status other than 429, the session has likely expired or been deleted; create a new session and retry. A 429 "already being accessed" means the session is alive but still held by the previous request, so retry the same session after a short backoff instead.

FAQ & Troubleshooting

My session returns a non-2xx status when I try to use it

If the status is anything other than 429, the session has expired or been deleted. Create a new session and retry. Sessions expire based on your plan's TTL (up to 90 days). A 429 means the live session is still attached to another client; see the next entry.

How do I clean up sessions I'm no longer using?

Send a DELETE request to the session.stop URL. Don't rely on TTL expiry alone, as idle sessions consume resources and can hit your session limit.

I get 429 "already being accessed" even though I send requests one at a time

Only one client can be attached to a session at a time, and the attachment isn't released the instant your previous request's HTTP response arrives. The browser detaches shortly after each request completes, so back-to-back requests can catch the session still held by the previous one. Retry with a short backoff (a few hundred milliseconds is usually enough). If a session is done for good, DELETE it via session.stop instead of leaving it to time out.

Next steps

Session reconnect

lightweight session reuse with the reconnect mutation

Cookie management

set cookies before navigation