Sessions

A Session is a running browser instance. Each Session has a unique CDP WebSocket URL that can be connected to and controlled by tools like Puppeteer and Playwright.

Create a Session

POST /v1/sessions
X-API-Key: <api_key>

# Optional parameters
{
  "contextId": "ctx_xxx",
  "useProxy": true,
  "proxyGeolocation": { "country": "US", "city": "newyork" },
  // or BYOP: "proxyId": "prx_xxx"  /  "proxy": { "type":"http", "host":"...", "port":8080 }
  "url": "https://example.com"
}

# Returns
{
  "id": "ses_xxxx",
  "cdpUrl": "wss://browserforest.com/ws/session/ses_xxxx",
  "status": "active",
  "proxy": null,
  "proxyProvider": "brightdata",
  "proxyGeolocation": { "country": "US", "city": "newyork" },
  "contextId": "ctx_xxx",
  "createdAt": "2024-01-01T00:00:00Z"
}

Managed residential proxy (useProxy)

Set useProxy: true to route traffic through platform Bright Data residential proxies. Requires Credits balance > 0. Mutually exclusive with proxy / proxyId. Proxy bandwidth is billed separately in Credits (default ~$10/GB). Response includes proxyProvider / proxyGeolocation and never returns upstream credentials.

List Sessions

GET /v1/sessions
X-API-Key: <api_key>

# Returns
[
  {
    "id": "ses_xxxx",
    "cdpUrl": "wss://browserforest.com/ws/session/ses_xxxx",
    "status": "running",
    "contextId": "ctx_xxx",
    "createdAt": "2024-01-01T00:00:00Z"
  }
]

Get a Session

GET /v1/sessions/:id
X-API-Key: <api_key>

# Returns same as above, single Session object

Stop a Session

DELETE /v1/sessions/:id
X-API-Key: <api_key>

# Returns 204 No Content

When a Session is stopped, if it is associated with a Context, the browser state (cookies, localStorage, etc.) is automatically saved to a Context snapshot, and cookies are synced to the database. The next Session using the same Context will automatically restore the previous state.

Session Cookies (Export / Inject)

No need to hand-write CDP — read and write cookies directly from active Sessions. Requires sessions:read permission (export) / sessions:write permission (inject).

Export Cookies

GET /v1/sessions/:id/cookies?domain=.example.com
X-API-Key: <api_key>

# Returns
{
  "sessionId": "ses_xxxx",
  "exportedAt": "2026-06-05T10:00:00Z",
  "count": 2,
  "cookies": [
    {
      "name": "session_token",
      "value": "...",
      "domain": ".example.com",
      "path": "/",
      "secure": true,
      "httpOnly": true
    }
  ]
}

Inject Cookies

PUT /v1/sessions/:id/cookies
X-API-Key: <api_key>
Content-Type: application/json

{
  "cookies": [
    { "name": "token", "value": "...", "domain": ".example.com", "path": "/", "secure": true }
  ],
  "mode": "merge"
}

# mode: merge (default) | replace
# Returns { "sessionId": "ses_xxxx", "count": 1, "mode": "merge" }

Controlling the Browser via CDP

Puppeteer

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: session.cdpUrl,
});
const page = await browser.newPage();
await page.goto('https://example.com');
await browser.disconnect(); // use disconnect(), not close() — won't close remote browser

Playwright

import { chromium } from 'playwright';

const browser = await chromium.connectOverCDP(session.cdpUrl);
const context = browser.contexts()[0];
const page = context.pages()[0];
await page.goto('https://example.com');
await browser.close();

Session Status

Parameters