How to Reconnect to a Browserless Browser Session
Reconnect to a live Browserless browser by requesting a handoff endpoint before disconnecting, then resume before its idle timeout or session limit expires.
To reconnect to a Browserless browser session, request reconnect information before the current client disconnects. Save the returned BrowserQL or WebSocket endpoint, detach without terminating the remote browser, and connect to that endpoint with valid authentication before the idle grace period expires. The idle timeout and your plan’s maximum session lifetime both apply.
This is a short handoff for a live browser. For longer gaps or separate runs, use Browserless’s Session API to persist browser profile data. Persisted cookies, localStorage, and cache can be restored after a process restart; open pages and in-memory state cannot.
How reconnection works
A reconnect endpoint identifies the still-running browser session. It is not a permanent session URL or a credential. You must create the handoff while connected, retain the endpoint, and authenticate the next connection as required by the client and endpoint.
- Connect to Browserless using your intended client and a valid API token.
- Perform the browser work you need to preserve.
- While still connected, request reconnect information and choose an idle timeout your plan permits. Browserless examples use
60000milliseconds (one minute); that is an example, not a universal entitlement. - Store the returned endpoint securely. Avoid logging token-bearing URLs.
- Detach using the supported method for your client. Do not terminate the remote browser if you intend to resume it.
- Connect to the returned endpoint before the idle timer expires.
- Terminate the session when finished if the API offers that operation.
Browserless’s reconnect workflow can support a handoff to another machine if that machine can reach the API, has the necessary authentication, and the session is still alive. [Browserless reconnect guide](https://docs.browserless.io/examples/reconnect) · [BrowserQL reconnect guide](https://docs.browserless.io/browserql/session-management/reconnect-to-browserless)
Choose the right persistence method
| Need | Method | What can survive | Limit |
|---|---|---|---|
| Pause briefly and resume the exact live browser | Reconnect operation or standard session | Same running process, open pages, and live page state | Idle grace period and absolute plan deadline both apply. |
| Reuse browser data across longer gaps or separate runs | Session API persistence | Cookies, localStorage, and cache | After a process restart, open pages, navigation history, scroll position, and in-memory state are gone. |
| Keep live pages available for a grace period using Session API | Session API process keep-alive, where supported | Live process state during the grace period and persisted profile data | Browserless documents a Puppeteer-specific limitation for processKeepAlive; check current support for your client. |
See Browserless’s guides to [continuing browser state across runs](https://docs.browserless.io/examples/persist-session) and [persisting state](https://docs.browserless.io/baas/session-management/persisting-state).
Reconnect with BrowserQL
The BrowserQL reconnect mutation returns a browserQLEndpoint for follow-up queries. The documented flow can also return a browserWSEndpoint for a CDP-based framework. Use the endpoint returned for your session rather than constructing one from memory.
mutation {
reconnect(timeout: 60000) {
browserQLEndpoint
browserWSEndpoint
}
}Send the mutation through the BrowserQL endpoint and authenticated connection documented for your account. Save the returned endpoint securely. For the next BrowserQL operation, submit the query to the returned browserQLEndpoint, with authentication as required by Browserless. Timeout limits depend on the account plan; check the current [BrowserQL reconnect documentation](https://docs.browserless.io/browserql/session-management/reconnect-to-browserless).
Reconnect with Puppeteer
For a standard Browserless session, use the documented CDP reconnect command before detaching, retain the returned WebSocket endpoint, then call Puppeteer’s disconnect() so the remote browser remains running. Connect to the returned endpoint with puppeteer.connect() before it expires. Include valid authentication as required by the endpoint.
const browser = await puppeteer.connect({ browserWSEndpoint: initialEndpoint });
// Keep the page open on the remote browser during the handoff.
const page = await browser.newPage();
await page.goto('https://example.com');
// Follow Browserless's documented standard-session CDP reconnect command
// while this connection is still active, and retain its returned endpoint.
const reconnectEndpoint = await requestReconnectEndpoint(browser);
// Detach this client without closing the remote browser.
await browser.disconnect();
// Later, connect to the returned endpoint using the authentication format
// required by your Browserless account and endpoint.
const resumedBrowser = await puppeteer.connect({
browserWSEndpoint: reconnectEndpoint,
});
console.log(await resumedBrowser.pages());requestReconnectEndpoint above represents the documented Browserless CDP command and must be implemented using the exact command and response shape in the [official reconnect example](https://docs.browserless.io/examples/reconnect); it is intentionally not a built-in Puppeteer method. The Browserless standard-session guide distinguishes Puppeteer’s disconnect() from terminating the remote browser. Do not replace disconnect with browser close when you need the process to remain alive.
Reconnect with Playwright
Browserless documents connecting to the returned WebSocket endpoint over CDP. The standard-session guide cautions that Puppeteer’s detach workflow does not directly carry over: Playwright does not expose Puppeteer’s disconnect(). Follow Browserless’s supported reconnect route for the specific Playwright and Browserless client versions you use, and verify that closing the local client leaves the remote process alive.
import { chromium } from 'playwright';
// Connect using the WebSocket endpoint returned by Browserless.
const browser = await chromium.connectOverCDP(reconnectEndpoint);
const contexts = browser.contexts();
const pages = contexts.flatMap((context) => context.pages());
console.log(pages.map((page) => page.url()));This snippet shows the receiving connection, not a complete detach implementation. Use the exact handoff and lifecycle procedure in the [Browserless reconnect guide](https://docs.browserless.io/examples/reconnect) for your supported setup; do not assume a Playwright browser close has the same semantics as Puppeteer’s disconnect.
Reconnect with BAP
In Browserless’s BAP API, page.reconnect() returns endpoint information for handoff. The returned endpoints omit credentials, so the new BAP WebSocket connection must supply its own valid token. Adapt the endpoint for the new BAP connection as the official guide describes.
const reconnectInfo = await page.reconnect();
// Persist reconnectInfo securely, then pass the endpoint and valid token
// to a new BAP connection using the documented BAP connection options.
console.log(reconnectInfo);The exact BAP endpoint adaptation and connection options depend on the returned values; follow [Browserless’s BAP reconnect guide](https://docs.browserless.io/bap/session-management/reconnects). Do not treat the endpoint as a credential or publish it in logs.
Timeouts, authentication, and session lifetime
- Idle timeout: the reconnect window is an idle grace period. BrowserQL documentation says each reconnect resets that idle timer.
- Absolute deadline: the plan’s maximum browser session lifetime is measured from browser start. Reconnecting does not extend this deadline indefinitely.
- Timeout units: the reconnect timeout is specified in milliseconds. Confirm the current plan limit before choosing a value.
- Authentication: provide a valid account API token in the manner required by the endpoint and client. BAP reconnect endpoints omit credentials; the next client must supply its own token.
- Endpoint secrecy: treat reconnect endpoints and tokens as sensitive. Keep them in a secret store or protected handoff channel, not application logs or source control.
- Cleanup: explicitly end sessions where the API provides termination. An idle session may continue occupying a concurrency slot until it expires.
For current account-specific limits, consult the [BrowserQL session guide](https://docs.browserless.io/browserql/session-management/reconnect-to-browserless) rather than copying a plan ceiling into application logic.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Connection error or expired endpoint | The idle timeout or absolute session lifetime elapsed. | Request reconnect information before detaching and connect sooner. Choose a timeout within your plan’s allowance. |
| Timeout rejected immediately | The requested reconnect timeout exceeds the plan limit. | Use a shorter timeout and check the current account documentation. |
| 401 Unauthorized | The follow-up connection lacks a valid token, or the endpoint was assumed to contain credentials. | Supply a valid token using the documented client method. BAP endpoints omit credentials. |
| Pages or state appear missing | The client connected to a different endpoint, or the browser process stopped. | Verify you used the returned endpoint for the same session. If the process restarted, restore persisted profile data; live pages and in-memory state cannot be recovered. |
| Remote browser closes when the first client exits | The client used a terminating close operation instead of a supported detach, or reconnect setup did not complete first. | Request reconnect information while connected and use the client-specific lifecycle procedure documented by Browserless. |
| 429 Too Many Requests | A previous session may still occupy concurrency until its timeout. | Terminate it explicitly if supported, or wait for expiry; also check for other active sessions. |
Performance, reliability, and cost considerations
Reconnection avoids repeating setup while the same remote process is alive, but it depends on reaching the endpoint before the idle window and absolute session deadline. A reconnect URL does not make the session durable. For work that must survive process restarts, persist browser profile data and design the workflow to navigate back to the required page.
Request only the idle window your handoff needs, subject to plan limits, and clean up sessions promptly to avoid holding concurrency unnecessarily. Browserless plan ceilings can change, so verify current limits and pricing in your account documentation. No fixed performance or cost estimate applies to every workload.
Or skip the browser setup
If you only need a website screenshot, you may not need to keep a remote browser session alive. ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);- Cookie banners are accepted and removed before capture; known consent platforms, newsletter popups, and chat widgets can also be removed.
- Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status.
- An MCP server gives AI agents tools for screenshots, page information, and PDF capture.
- 1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo and get 1,000 free screenshots a month with no card.
FAQ
Can I reconnect from a different machine?
Yes, if the new machine can reach Browserless, has valid authentication, and connects before the session’s idle window or absolute lifetime ends.
Does the reconnect endpoint work indefinitely?
No. The idle timeout and plan’s absolute session deadline both limit the live browser.
Will Session API persistence reopen my tabs?
No. It can restore cookies, localStorage, and cache, but a restarted browser does not retain open pages or in-memory state.
Should I use reconnection or persistence?
Use reconnection for a brief handoff that must preserve the live browser. Use Session API persistence to reuse stored browser data across runs or process restarts.
