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 or Puppeteer
  • Open/close tabs (targets) and query browser info
  • Integrate 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 JS SDK

​
Option 1 — JavaScript SDK

You can use a tiny SDK to simplify session lifecycle and CDP discovery. Download the latest version here, then import it in your app. 
// import the class from your local path where you saved sdk.js
import { BrowserSDK } from './sdk.js'

async function main() {
  const apiKey = process.env.BROWSER_API_KEY! // set your Browser API key
  const sdk = new BrowserSDK(apiKey)

  // 1) Create a session (optionally pass targeting info)
  //    The SDK retries a few times and waits ~20s max for the session to become active
  const session = await sdk.createSession({ /* e.g., region: 'gcp-usc1-1' */ })
  console.log('Session created:', session.sessionId)

  // 2) Get a CDP URL and connect with Playwright
  const cdpUrl = await sdk.getBrowserCDPUrl()
  console.log('CDP URL:', cdpUrl)
}

main().catch(console.error)

​
Extra SDK capabilities

The SDK you downloaded includes convenience methods you might find useful:
  • createSession(targeting?: object) — POST /v1/consumer/session and wait until active (up to ~20s)
  • getSessionStatus() — GET /v1/consumer/session?sessionId=…
  • getBrowserCDPUrl() — Resolve a CDP URL suitable for Playwright/Puppeteer
  • getBrowserInfo() — GET /json/version raw fields from the remote browser
  • createPage(url?: string) — Open a new tab/target (default about:blank)
  • closePage(targetId: string) — Close a tab/target
  • endSession() — DELETE /v1/consumer/session?sessionId=…
Use these primitives to structure multi-step flows (navigate, extract, upload, etc.).

​
Option 2 — REST API (fetch/curl)

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://browser-api.browser.cash/v1/consumer/session \
  -d '{}'

​
2) Wait for the session to become active

async function waitForActive(sessionId: string, apiKey: string, timeoutMs = 20_000) {
  const start = Date.now()
  const url = `https://browser-api.browser.cash/v1/consumer/session?sessionId=${encodeURIComponent(sessionId)}`
  while (true) {
    const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } })
    const json = await res.json()
    if (json?.session?.status === 'active') return json.session
    if (Date.now() - start > timeoutMs) throw new Error('Timed out waiting for active session')
    await new Promise(r => setTimeout(r, 1000))
  }
}

​
3) Get a CDP URL

Once the session is active, request the remote browser info and read the webSocketDebuggerUrl. 
# Replace <SESSION_ID> and region host as needed
curl -s https://gcp-usc1-1.milan-taurine.tera.space/v1/consumer/<SESSION_ID>/json/version | jq '.'
That endpoint returns a local-style webSocketDebuggerUrl (e.g., ws://127.0.0.1/devtools/browser/...). Construct an external CDP URL by swapping the prefix: 
function toExternalCdp(sessionId: string, localUrl: string) {
  // ws://127.0.0.1/devtools/browser/...  ->  wss://<milan-host>/v1/consumer/<sessionId>/devtools/browser/...
  const milanHost = 'gcp-usc1-1.milan-taurine.tera.space'
  return localUrl.replace('ws://127.0.0.1', `wss://${milanHost}/v1/consumer/${sessionId}`)
}
Use that final CDP URL with Playwright/Puppeteer — or see the guide: /browser-api/guides/cdp-playwright.

​
4) Open a new page (tab)

# URL is provided as the query string; defaults to about:blank when omitted
curl -X PUT \
  https://gcp-usc1-1.milan-taurine.tera.space/v1/consumer/<SESSION_ID>/json/new?https%3A%2F%2Fexample.com

​
5) Stop the session

curl -X DELETE \
  -H "Authorization: Bearer $BROWSER_API_KEY" \
  "https://browser-api.browser.cash/v1/consumer/session?sessionId=<SESSION_ID>"

​
Timeouts, retries, and tips

  • Session activation: allow up to ~20 seconds for the browser to boot on cold nodes
  • The SDK internally retries createSession up to 3 times with small backoff and waits for active
  • 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

​
See also