API Reference

Sessions

Sessions are managed browser instances running in the cloud. Create a session, connect to it via CDP WebSocket, control the browser, and release it when done.

Session Lifecycle

text

created → active → released (manual) or expired (timeout)

Sessions start as active immediately upon creation. They become released when explicitly closed, orexpired when the timeout elapses. If an error occurs during browser launch, the status is error.

Create Session

POST/v1/sessions

Launch a new managed browser session.

Parameters

Name	Type	Required	Default	Description
`sessionId`	`string`	No	`—`	Custom session ID. Auto-generated if omitted.
`proxyUrl`	`string`	No	`—`	Proxy URL for this session (HTTP or SOCKS5). Overrides the global PROXY_URL.
`stealth`	`"none" \| "basic" \| "full"`	No	`"full"`	Anti-detection level.
`userAgent`	`string`	No	`—`	Custom User-Agent string.
`viewport`	`{ width, height }`	No	`{ 1920, 1080 }`	Browser viewport dimensions in pixels.
`timeout`	`number`	No	`1800000`	Session timeout in milliseconds (max 86400000 = 24h).
`profileId`	`string`	No	`—`	Browser profile ID. Loads saved cookies and localStorage.
`blockAds`	`boolean`	No	`false`	Block ads and trackers.
`cookies`	`Cookie[]`	No	`—`	Cookies to inject. Each: { name, value, domain, path? }.
`timezone`	`string`	No	`—`	Timezone override, e.g. 'America/New_York'.
`locale`	`string`	No	`—`	Locale override, e.g. 'en-US'.
`headers`	`Record<string, string>`	No	`—`	Custom headers to set on all page requests.

Request Body

{
  "stealth": "full",
  "viewport": { "width": 1920, "height": 1080 },
  "timeout": 3600000,
  "proxyUrl": "socks5://user:pass@proxy.example.com:1080"
}

Response

{
  "id": "sess_abc123def456",
  "status": "active",
  "websocketUrl": "ws://api.browsefleet.com/cdp/sess_abc123def456",
  "viewerUrl": "https://api.browsefleet.com/v1/sessions/sess_abc123def456/live",
  "createdAt": "2026-04-02T12:00:00.000Z",
  "expiresAt": "2026-04-02T13:00:00.000Z",
  "timeout": 3600000,
  "stealth": "full",
  "viewport": { "width": 1920, "height": 1080 }
}

curl -X POST https://api.browsefleet.com/v1/sessions \
  -H "Content-Type: application/json" \
  -H "x-api-key: bf_your_api_key" \
  -d '{
    "stealth": "full",
    "viewport": { "width": 1920, "height": 1080 },
    "timeout": 3600000
  }'

List Sessions

GET/v1/sessions

List all active browser sessions.

Response

{
  "sessions": [
    {
      "id": "sess_abc123",
      "status": "active",
      "websocketUrl": "ws://api.browsefleet.com/cdp/sess_abc123",
      "viewerUrl": "https://api.browsefleet.com/v1/sessions/sess_abc123/live",
      "createdAt": "2026-04-02T12:00:00.000Z",
      "expiresAt": "2026-04-02T12:30:00.000Z",
      "timeout": 1800000,
      "stealth": "full",
      "viewport": { "width": 1920, "height": 1080 }
    }
  ],
  "count": 1
}

curl https://api.browsefleet.com/v1/sessions \
  -H "x-api-key: bf_your_api_key"

Get Session

GET/v1/sessions/:id

Get details of a specific session by ID.

Response

{
  "id": "sess_abc123",
  "status": "active",
  "websocketUrl": "ws://api.browsefleet.com/cdp/sess_abc123",
  "viewerUrl": "https://api.browsefleet.com/v1/sessions/sess_abc123/live",
  "createdAt": "2026-04-02T12:00:00.000Z",
  "expiresAt": "2026-04-02T12:30:00.000Z",
  "timeout": 1800000,
  "stealth": "full",
  "viewport": { "width": 1920, "height": 1080 }
}

curl https://api.browsefleet.com/v1/sessions/sess_abc123 \
  -H "x-api-key: bf_your_api_key"

Release Session

POST/v1/sessions/:id/release

Release (close) a single session. The browser process is terminated and resources are freed.

Response

{ "released": true }

curl -X POST https://api.browsefleet.com/v1/sessions/sess_abc123/release \
  -H "x-api-key: bf_your_api_key"

Release Batch

POST/v1/sessions/release

Release multiple sessions at once, or all sessions if no IDs are provided.

Parameters

Name	Type	Required	Default	Description
`ids`	`string[]`	No	`—`	Array of session IDs to release. If omitted, releases all active sessions.

Request Body

{
  "ids": ["sess_abc123", "sess_def456"]
}

Response

{ "released": 2 }

# Release specific sessions
curl -X POST https://api.browsefleet.com/v1/sessions/release \
  -H "Content-Type: application/json" \
  -H "x-api-key: bf_your_api_key" \
  -d '{ "ids": ["sess_abc123", "sess_def456"] }'

# Release all sessions
curl -X POST https://api.browsefleet.com/v1/sessions/release \
  -H "Content-Type: application/json" \
  -H "x-api-key: bf_your_api_key" \
  -d '{}'

CDP WebSocket Connection

After creating a session, use the websocketUrl to connect any CDP-compatible tool. BrowseFleet transparently proxies the Chrome DevTools Protocol between your client and the browser.

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: session.websocketUrl,
});
const page = await browser.newPage();
await page.goto('https://example.com');

// ... use the page normally ...

await browser.disconnect();

Live Viewer (SSE)

GET/v1/sessions/:id/live

Server-Sent Events stream of JPEG screenshots at 2fps. Useful for debugging and monitoring sessions in real time. Streams for up to 5 minutes.

Response

data: { "screenshot": "<base64-jpeg>" }

data: { "screenshot": "<base64-jpeg>" }

...

Session Object Schema

Field	Type	Description
`id`	string	Unique session identifier
`status`	string	"active" \| "released" \| "expired" \| "error"
`websocketUrl`	string	CDP WebSocket URL for connecting automation tools
`viewerUrl`	string	URL for the live session viewer (SSE)
`createdAt`	string	ISO 8601 creation timestamp
`expiresAt`	string	ISO 8601 expiration timestamp
`timeout`	number	Session timeout in milliseconds
`stealth`	string	Stealth level used
`viewport`	object	Viewport dimensions (width, height)
`proxyUrl`	string?	Proxy URL if configured
`profileId`	string?	Browser profile ID if used