Skip to main content

​
What is the Session API?

The Session API gives you full, programmatic control over managed Chrome sessions:
  • Create/stop sessions on demand
  • Retrieve a CDP URL to drive the browser with Playwright, Puppeteer, or any CDP-compatible tool
  • Integrate browser sessions into backends, workflows, and automations
If you just want a quick, zero-setup CDP URL, see Quickconnect instead.

​
Prerequisites

  • A Browser API key (from the Dashboard)
  • Any HTTP client (curl/fetch) or Node.js 18+ if using the TypeScript SDK

​
Option 1 — TypeScript SDK

You can install our SDK from NPM with: 
npm install @browsercash/sdk
Then use the following code to create and connect to a browser session: 
import BrowsercashSDK from '@browsercash/sdk';

async function main() {
  const client = new BrowsercashSDK({
    apiKey: process.env.BROWSER_API_KEY!,
  });

  // 1) Create a session
  const session = await client.browser.session.create();
  console.log('Session created:', session.sessionId);

  // 2) Get a CDP URL
  console.log('CDP URL:', session.cdpUrl);
}

main().catch(console.error);
You can also target specific regions or nodes by passing options to create(): 
const session = await client.browser.session.create({
  country: 'US', // Filter to US nodes
  type: 'hosted' // Only use nodes hosted in our data centers, not distributed consumer devices
});
If you want to launch a session on a node you used in the past, you can pass nodeId to create(). If the node is offline, your request will fail.

​
Option 2 — REST API

You can call the REST endpoints directly if you prefer no SDK.

​
1) Create a session

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BROWSER_API_KEY" \
  https://api.browser.cash/v1/browser/session \
  -d '{}'

​
2) Get the CDP URL

Once the session request returns, the cdpUrl field in the response will be populated. Use that CDP URL with Playwright/Puppeteer, or any other tool that supports CDP connections.

​
3) Stop the session

Once you’re done with the session, be sure to stop it to avoid unnecessary billing: 
curl -X DELETE \
  -H "Authorization: Bearer $BROWSER_API_KEY" \
  "https://api.browser.cash/v1/browser/session?sessionId=<SESSION_ID>"

​
Notes

  • Sessions may take up to 20 seconds to start
  • CDP URLs expire with the session; create a new session to get a fresh URL
  • For long-running automations, reconnect your client if the network blips — the remote browser keeps running until you stop it, up to one hour
  • Session entries may be deleted at any time after completion.

​
See also