> ## Documentation Index
> Fetch the complete documentation index at: https://docs.driver.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# View a Browser Session

> Watch and interact with a running Driver browser session.

The live viewer lets you inspect a running browser and manually interact with it during development or debugging.

## Open the Viewer

Create a viewer URL from the session `cdpUrl`:

```text theme={null}
https://viewer.driver.dev?ws=<cdp-url>
```

<CodeGroup>
  ```typescript TypeScript theme={null}
  const session = await client.browser.session.create({ type: "hosted" });
  const viewerUrl = `https://viewer.driver.dev?ws=${session.cdpUrl}`;

  console.log(viewerUrl);
  ```

  ```python Python theme={null}
  viewer_url = f"https://viewer.driver.dev?ws={session['cdpUrl']}"
  print(viewer_url)
  ```
</CodeGroup>

<Note>
  Keep the Driver session active while the viewer is connected. Stop the session when you are finished debugging.
</Note>

## Viewer Parameters

| Parameter | Description                                  |
| --------- | -------------------------------------------- |
| `ws`      | CDP WebSocket URL from the session response. |
| `theme`   | Optional viewer theme: `light` or `dark`.    |

## Poll Session Status

Use the session status to wait for a browser to become available or to detect that it has ended.

<CodeGroup>
  ```typescript TypeScript theme={null}
  async function waitForActiveSession(sessionId: string, timeoutMs = 30000) {
    const startedAt = Date.now();

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

      if (session.status === "active" && session.cdpUrl) return session;
      if (session.status === "completed" || session.status === "error") {
        throw new Error(`Session ended with status: ${session.status}`);
      }

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

    throw new Error("Timed out waiting for session");
  }
  ```

  ```python Python theme={null}
  import os
  import time
  import requests

  def wait_for_active_session(session_id: str, timeout_seconds: int = 30):
      started_at = time.time()

      while time.time() - started_at < timeout_seconds:
          resp = requests.get(
              "https://api.driver.dev/v1/browser/session",
              headers={"Authorization": f"Bearer {os.getenv('DRIVER_API_KEY')}"},
              params={"sessionId": session_id},
          )
          resp.raise_for_status()
          session = resp.json()

          if session["status"] == "active" and session.get("cdpUrl"):
              return session
          if session["status"] in ("completed", "error"):
              raise RuntimeError(f"Session ended with status: {session['status']}")

          time.sleep(1)

      raise TimeoutError("Timed out waiting for session")
  ```
</CodeGroup>

## Status Values

| Status      | Meaning                                            |
| ----------- | -------------------------------------------------- |
| `starting`  | Session is being created.                          |
| `active`    | Session is running and can accept CDP connections. |
| `completed` | Session has stopped successfully.                  |
| `error`     | Session failed or ended with an error.             |