---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/observability/record-a-har-file
markdown_url: https://steel.dev/docs/observability/record-a-har-file.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Record a HAR file
description: Save a session's requests and responses, with their headers and bodies, as a HAR file with Playwright, and a trace of each page.
summary: Save a session's requests and responses, with their headers and bodies, as a HAR file with Playwright, and a trace of each page.
type: how-to
reviewed: 2026-11-18
prerequisites: []
related:
  - https://steel.dev/docs/observability/hand-control-to-a-human.md
  - https://steel.dev/docs/observability/recordings.md
  - https://steel.dev/docs/observability/logs.md
  - https://steel.dev/docs/observability/agent-traces.md
  - https://steel.dev/docs/observability/signals.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Record a HAR file

A HAR file (HTTP Archive) holds a browser's network traffic: each request and response, with its headers, cookies, timings and body. Record one to study how a site loads its data, to call a site's API directly, or to keep a full record of a run. Steel's [logs](https://steel.dev/docs/observability/logs) hold each request's URL, method and status, but not its headers or body.

Steel does not save HAR files itself. Playwright records one over its connection to the session, and writes it on the machine that runs your code.

## Before you begin

Put your Steel API key in the `STEEL_API_KEY` environment variable. Then install the Steel SDK and Playwright 1.60 or later, the first version with `tracing.startHar`. You do not need to run `playwright install`, because the program uses a browser that Steel runs.

**TypeScript**

```sh
npm install steel-sdk playwright
```

**Python**

```sh
python3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwright
```

## Record the network traffic

This program starts a HAR recording and a Playwright trace on the session's browser context, opens a page, and saves both files.

**TypeScript**

```ts file=har.mts
import Steel from "steel-sdk";
import { chromium } from "playwright";

const client = new Steel();
const session = await client.sessions.create();

try {
  const browser = await chromium.connectOverCDP(session.websocketUrl);

  try {
    const context = browser.contexts()[0];
    const page = context.pages()[0] ?? (await context.newPage());

    const timestamp = Date.now();
    const harFile = `recording-${timestamp}.har`;
    const traceFile = `trace-${timestamp}.zip`;

    await context.tracing.startHar(harFile, {
      urlFilter: "**/*",
      content: "embed",
      mode: "full",
    });
    await context.tracing.start({
      screenshots: true,
      snapshots: true,
      sources: true,
    });

    try {
      await page.goto("https://news.ycombinator.com");
    } finally {
      try {
        await context.tracing.stop({ path: traceFile });
      } finally {
        await context.tracing.stopHar();
      }
    }

    console.log(`HAR: ${harFile}, Trace: ${traceFile}`);
  } finally {
    await browser.close();
  }
} finally {
  await client.sessions.release(session.id);
}
```

**Python**

```python file=har.py
import time

from playwright.sync_api import sync_playwright
from steel import Steel

client = Steel()
session = client.sessions.create()

try:
    with sync_playwright() as playwright:
        browser = playwright.chromium.connect_over_cdp(session.websocket_url)

        try:
            context = browser.contexts[0]
            page = context.pages[0] if context.pages else context.new_page()

            timestamp = int(time.time() * 1000)
            har_file = f"recording-{timestamp}.har"
            trace_file = f"trace-{timestamp}.zip"

            context.tracing.start_har(har_file, url_filter="**/*", content="embed", mode="full")
            context.tracing.start(screenshots=True, snapshots=True, sources=True)

            try:
                page.goto("https://news.ycombinator.com")
            finally:
                try:
                    context.tracing.stop(path=trace_file)
                finally:
                    context.tracing.stop_har()

            print(f"HAR: {har_file}, Trace: {trace_file}")
        finally:
            browser.close()
finally:
    client.sessions.release(session.id)
```

The program records the browser context that the session already has, `contexts()[0]`, and does not create a new one. The options of `startHar` (`start_har` in Python) set what the HAR file keeps:

| Option | What it does |
| - | - |
| `urlFilter` | Keeps only the requests whose URL matches this glob or regular expression. `**/*` keeps every request. |
| `content` | `embed` keeps each response's body in the HAR file. When the path ends in `.zip`, the default is `attach`, which saves the bodies as separate files in the archive. |
| `mode` | `full` keeps the sizes, timings, cookies and pages. `minimal` keeps only what Playwright needs to replay the requests. |

The trace holds a snapshot of the page's DOM and a screenshot at each action. So it has the page after its scripts ran, which the HAR file does not have. Playwright's [tracing.startHar](https://playwright.dev/docs/api/class-tracing#tracing-start-har) and [Trace viewer](https://playwright.dev/docs/trace-viewer) docs have every option.

Run the program:

**TypeScript**

```sh
npx tsx har.mts
```

**Python**

```sh
python har.py
```

It writes both files in the folder where it runs when it stops the recordings, and prints their names:

**TypeScript**

```text nocopy
HAR: recording-1795058880467.har, Trace: trace-1795058880467.zip
```

**Python**

```text nocopy
HAR: recording-1795059231523.har, Trace: trace-1795059231523.zip
```

On a server whose disk is read-only but for a temporary folder, such as AWS Lambda, write them to `/tmp` and upload them to your own storage.

> **Warning**
>
> A HAR file holds the session's cookies and the headers that sign it in to sites, such as `Authorization`. Store it as you store credentials, and delete it when you no longer need it.

## Check that it worked

Open the HAR file in the Network panel of Chrome DevTools, which imports HAR files, as [Chrome's Network reference](https://developer.chrome.com/docs/devtools/network/reference) explains. It lists the requests that loaded `news.ycombinator.com`, each with its headers and its response. Then open the trace with `npx playwright show-trace` and the trace's file name (`playwright show-trace` in Python). It shows the `goto` action with a snapshot of the page.

## What a HAR file leaves out

- The first requests of a tab that a page opens, such as a link with `target="_blank"` or a call to `window.open`. They start before Playwright attaches to the tab. A tab that your code opens with `newPage` (`new_page` in Python) and then `goto` is recorded from its first request.
- The page after its scripts ran. The HAR file has the HTML that the site sent, and the trace has the page as it showed.

## Next steps

- [Logs](https://steel.dev/docs/observability/logs): Read a session's requests, responses and page errors without recording anything.
- [Agent traces](https://steel.dev/docs/observability/agent-traces): See each click and input of a run, in step with the recording.
- [Playwright](https://steel.dev/docs/integrations/playwright): Connect Playwright to a session, and keep the code that you already have.
