> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/headless-browser/session-inspection-and-recording.md).

# Session Inspection & Recording

See how to debug automation sessions via a real-time graphical interface.

Oxylabs Headless Browser provides [**Session Inspection**](#session-inspection-vnc) and [**Session Recording**](#session-recording) to observe browser automation in real time or review video playbacks of past sessions. These visual debugging features allow you to:

* Diagnose complex issues that aren't evident from logs or error messages
* Understand page rendering exactly as the browser sees it
* Verify proper execution of your automation workflows
* Troubleshoot unexpected behavior in real-time

Both tools are available directly under the `hb.oxylabs.io` domain, alongside your connection endpoint:

* Dashboard at `hb.oxylabs.io/dashboard`
* Session inspection at `hb.oxylabs.io/novnc`

{% hint style="warning" %}
**Attention:** The dashboard and session inspection tools have been moved form `headlesify.io` into `hb.oxylabs.io`.

Please update your integration until **October 1st**. From that date, traffic to the old domains will be automatically routed to the new ones.
{% endhint %}

## Session Inspection (VNC) <a href="#session-inspection-vnc" id="session-inspection-vnc"></a>

Session Inspection tool is a debugging feature that uses VNC (Virtual Network Computing) to provide real-time visual access to your browser automation sessions.

The recommended way to watch a live session is through the Dashboard at `hb.oxylabs.io/dashboard`, where you can view active sessions without any extra setup.

If you need a direct viewer link (e.g. to embed in your own tooling) you can retrieve the `hb.oxylabs.io/novnc` viewer URL from the session ID:

```javascript
const cdp = await ctx.newCDPSession(page);
const { value: sid } = await cdp.send("__session_id");
const vncUrl = `https://hb.oxylabs.io/novnc/?id=${sid}`;
console.log(vncUrl);  // open this URL in your browser
```

{% hint style="warning" %}
**Attention:** Session Inspection is being fully integrated into the main dashboard. Once migration is complete, the dashboard will be the single place to monitor and inspect live sessions, and this page will be updated accordingly.
{% endhint %}

## Session Recording

Record your entire Headless Browser session as a video for debugging, auditing, or reviews. To record a session, add the `record=true` query parameter to your connection URL:

```bash
wss://USER:PASS@hb.oxylabs.io?record=true
```

By default, every account can store up to **10 recordings**. If you need a higher limit, contact Oxylabs support ([live chat](https://oxylabs.io/) or [email](mailto:support@oxylabs.io)) or your Dedicated Account Manager.

{% hint style="info" %}
When using [**persistent sessions**](/products/headless-browser/persistent-sessions-and-profiles.md#persistent-sessions), recordings are stored as a single continuous video across all reconnections to that session, rather than creating a separate recording file for each connection.
{% endhint %}

### Customizing recording names

Organize and filter your recordings inside your dashboard by assigning custom names to your videos using the `record_name` parameter. You can use alphanumeric characters with hyphens and underscores, up to a maximum length of 64 characters (`^[a-zA-Z0-9_-]{1,64}$`):

```bash
wss://USER:PASS@hb.oxylabs.io?record=true&record_name=payment_checkout_flow_01
```

### Accessing playbacks

All completed recordings are automatically encoded and saved to your Dashboard. You can search, filter, view, and delete your recordings directly at `hb.oxylabs.io/dashboard`.

## Code examples

The following Node.js example shows how to connect to the browser with recording enabled, extract the session ID programmatically, and output the live inspection link to your console.

{% hint style="success" %}
Features support both Playwright and Puppeteer libraries.
{% endhint %}

```javascript
import { chromium } from "playwright";

const username = "USERNAME_abc12";
const password = "PASSWORD";
const endpoint = "hb.oxylabs.io";
// Enable video recording under a custom name
const params = "record=true&record_name=chrome_vnc_test";
const browserUrl = `wss://${username}:${password}@${endpoint}?${params}`;

(async () => {
    // Connect to the browser
    const browser = await chromium.connectOverCDP(browserUrl);
    const ctx = browser.contexts()[0] || (await browser.newContext());
    const page = ctx.pages()[0] || (await ctx.newPage());
    try {
        // 1. Initialize a CDP session on the active page
        const cdpSession = await ctx.newCDPSession(page);
        
        // 2. Query the custom session identifier
        const { value: sessionId } = await cdpSession.send("__session_id");
        
        // 3. Construct and output the session inspection link
        console.log(`Live session inspection link: https://hb.oxylabs.io/novnc/?id=${sessionId}`);
        // Execute your automation steps
        await page.goto("https://example.com");
        
        // Hold session open briefly to allow visual monitoring
        await new Promise(resolve => setTimeout(resolve, 10000));
    } catch (error) {
        console.error("Visual session execution failed:", error.message);
    } finally {
        await browser.close();
        console.log("Recording compiled. Access playback at https://hb.oxylabs.io/dashboard");
    }
})();
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/products/headless-browser/session-inspection-and-recording.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.