Getting started with BAP
Install @browserless.io/bap-ts, connect to a BrowserQL endpoint, and run a session that navigates to a page and reads its title. By the end you'll have a working script and know which connection options control timeouts and transport.
- A Browserless API token from your account dashboard
- npm 11.10 or later (the package declares
engines.npm >= 11.10.0) - A BrowserQL WebSocket endpoint for your preferred region and browser
- Read the BAP overview first if you haven't picked BAP over BrowserQL or BaaS yet
Get your API token
Copy your token from the account dashboard before continuing. BAP appends it to the endpoint as ?token= when the WebSocket opens, so a missing token fails at connection time rather than on your first method call.
Install the library
npm install @browserless.io/bap-ts
Connect and run
Swap in your token and this runs as-is:
import Browserless from "@browserless.io/bap-ts";
const TOKEN = "YOUR_API_TOKEN_HERE";
// connect() is synchronous and opens no socket. The WebSocket opens on newPage().
const browser = Browserless.connect({
browserWSEndpoint: "wss://production-sfo.browserless.io/chromium/bql",
token: TOKEN,
});
const page = await browser.newPage();
await page.goto("https://example.com");
console.log(await page.title());
// close() closes every page and its socket, freeing your account concurrency.
await browser.close();
Expected output
Example Domain
Pick an endpoint
The quickstart uses Chromium. Swap the path for a different browser:
wss://production-sfo.browserless.io/chromium/bql # Chromium, the default
wss://production-sfo.browserless.io/chrome/bql # Google Chrome
wss://production-sfo.browserless.io/stealth/bql # Managed stealth browser
The endpoint must end in /bql. The same host also serves CDP endpoints such as /chromium, and those don't speak BrowserQL. See Connection URLs and Endpoints for every region and route.
Connection options
| Option | Type | Default | Description |
|---|---|---|---|
browserWSEndpoint | string | — | BrowserQL WebSocket endpoint. Optional only when you supply a custom transport that owns its own connection |
token | string | — | Your API token. Appended to the endpoint as ?token= when the connection opens |
timeout | number | 30000 | Default per-operation timeout in milliseconds |
transport | TransportFactory | Built-in WebSocketTransport | Replace the built-in socket with your own transport, Puppeteer-style |
Each call to browser.newPage() opens its own WebSocket connection, so a script that runs three pages holds three sockets until you call close().
FAQ & Troubleshooting
My connection fails immediately with a ConnectionError
Check that the endpoint ends in /bql. wss://production-sfo.browserless.io/chromium is a CDP endpoint and won't speak BrowserQL. Then confirm your token is set, since it's appended when the socket opens and a missing one fails at connect time.
Why did my operation time out after 30 seconds?
30000 is the default per-operation timeout. Raise it globally with timeout on Browserless.connect(), or per call with the timeout option that navigation, selector, and CAPTCHA methods accept.
Do I need to call browser.close()?
Yes. close() closes every page and its WebSocket. Leaving sessions open holds a browser against your account concurrency until it times out.
Can I run this in the browser instead of Node.js?
Yes. The package is isomorphic and bundlers pick the native WebSocket build automatically. Two things change: path on screenshot() and pdf() rejects, and your token ends up in the client bundle. See Node.js and browser support.