Viewing a Browser Session

Watch and interact with your browser sessions live

View your browser sessions in real-time and perform manual actions directly in your browser.

Live Session Viewer

Browser Cash provides a live viewer where you can watch and interact with your browser session in real-time.

To view a session, construct the viewer URL using your session’s cdpUrl:

https://dash.browser.cash/cdp_tabs?ws=<encoded-cdp-url>&theme=light

1. Create a session

   Start a browser session and retrieve the cdpUrl from the response.

2. URL-encode the cdpUrl

   Encode the WebSocket URL so it can be passed as a query parameter.

3. Open the viewer

   Navigate to the constructed URL in your browser to view the session live.

TypeScript

const session = await client.browser.session.create();

// URL-encode the CDP WebSocket URL
const encodedWs = encodeURIComponent(session.cdpUrl);
const viewerUrl = `https://dash.browser.cash/cdp_tabs?ws=${encodedWs}&theme=light`;

console.log("View your session live:", viewerUrl);

The live viewer allows you to see exactly what your automation is doing and manually interact with the browser — click elements, type text, or navigate to different pages.

Viewer Parameters

Parameter	Values	Description
ws	URL-encoded WSS	The CDP WebSocket URL from your session
theme	light, dark	Viewer color theme

---

Get Session Details

TypeScript

const session = await client.browser.session.get({
  sessionId: "sess_abc123xyz",
});

console.log(session);

Response

{
  "sessionId": "sess_abc123xyz",
  "status": "active",
  "servedBy": "node-us-east-1",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "stoppedAt": null,
  "cdpUrl": "wss://cdp.browser.cash/sess_abc123xyz"
}

Session Status Values

Status	Description
active	Session is running and accepting connections
stopped	Session has been terminated
failed	Session failed to start

List All Sessions

Retrieve paginated list of all your sessions:

TypeScript

const sessions = await client.browser.sessions.list({
  page: 1,
  pageSize: 20,
});

console.log(sessions);

Pagination Parameters

Parameter	Type	Default	Description
page	number	1	Page number
pageSize	number	20	Results per page

Monitoring Sessions

Poll session status to monitor long-running tasks:

TypeScript

async function waitForSession(sessionId: string, timeout = 30000) {
  const start = Date.now();

  while (Date.now() - start < timeout) {
    const session = await client.browser.session.get({ sessionId });

    if (session.status === "active" && session.cdpUrl) {
      return session;
    }

    if (session.status === "failed") {
      throw new Error("Session failed to start");
    }

    await new Promise((r) => setTimeout(r, 1000));
  }

  throw new Error("Session startup timeout");
}

Next Steps

• Managing Sessions — Stop sessions and clean up resources
• Browser Profiles — Persist browser state across sessions