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

# heymcp export

> Export a session's tool calls.

```bash theme={null}
heymcp export <session-id>
```

Writes a session's history to stdout. Get the id from
[`heymcp sessions`](/cli/sessions) or from the inspector URL.

```bash theme={null}
heymcp export 01J8XK... > afternoon.json
heymcp export 01J8XK... --format vizra -o fixtures/pizza.json
```

<Note>
  Export reads from stored history, so it only works while the session is within
  your [retention window](/concepts/sessions#retention) — 24 hours on Hobby,
  7 days on Pro. An expired session exports nothing.
</Note>

## Options

<ParamField path="--format <json|vizra>" default="json">
  Which shape to write.
</ParamField>

<ParamField path="-o, --out <FILE>">
  Write to a file instead of stdout.
</ParamField>

## The `json` format

Everything, losslessly. The full session metadata plus every raw event in
arrival order:

```json theme={null}
{
  "session": {
    "id": "01J8XK...",
    "slug": "amber-jetty",
    "public_url": "https://amber-jetty.t.heymcp.dev/mcp",
    "opened_at": "2026-08-15T13:02:11+00:00",
    "closed_at": "2026-08-15T17:48:03+00:00"
  },
  "events": [ ... ]
}
```

Requests and responses appear as **separate events**, exactly as they arrived.
That's precisely why they're stored separately — the inspector folds them
together for reading, but an export that folded them would lose information.

Use this when you want the whole picture: a bug report, an archive before a
session expires, or your own analysis.

## The `vizra` format

Deliberately narrow: ordered tool calls with their arguments, results and the
client that made them. Enough to replay a session deterministically, and
nothing else.

```json theme={null}
{
  "format": "vizra/mcp-session@1",
  "session": {
    "id": "01J8XK...",
    "slug": "amber-jetty",
    "recorded_at": "2026-08-15T13:02:11+00:00"
  },
  "calls": [
    {
      "tool": "place_order",
      "arguments": { "collection_time": "7pm" },
      "result": null,
      "ok": false,
      "latency_ms": 120,
      "client": "claude_ai",
      "at": "2026-08-15T14:02:31+00:00"
    }
  ]
}
```

`ok` is `null` when no result was ever paired to the call — the agent asked and
nothing came back.

Use this when you're turning real agent behaviour into an evaluation fixture.
The interesting property is that the arguments are what a real model actually
sent, not what you imagined it would send.

## A worked use

The classic one. An agent breaks your tool by sending `"7pm"` for a date:

```bash theme={null}
heymcp export 01J8XK... --format vizra -o tests/fixtures/pizza-7pm.json
```

Now that failure is a regression test, and it's a failure a human wouldn't have
thought to write.