How to Read LangSmith Traces Outside the Dashboard

If you build with LangChain or LangGraph, you already know the pain. A single agent run can produce hundreds of nested spans, each with its own prompt, tool call, retrieval hit, and token accounting. LangSmith is great at capturing all of it, but the dashboard was built for debugging live runs, not for careful rereading. When you want to sit down with a trace and understand what your agent did, the browser UI starts working against you. This guide covers how to pull LangSmith traces out of the dashboard, convert them into readable markdown, and open them in a proper reader.

If you already know why you want that, skip to the export section. Otherwise the first part explains why the built-in view runs out of runway once traces get long, and where the friction shows up in day to day work. The workflow below assumes a Python environment and an API key, but the ideas port cleanly to the TypeScript SDK if that is your stack. Everything else is standard markdown tooling that any team can adopt in an afternoon.

Why the LangSmith dashboard breaks down for long traces

The LangSmith UI is optimized for one job: showing you the most recent run so you can spot the bug. Timeline on the left, span detail on the right, collapsible JSON in the middle. It works beautifully for a five step chain that failed twenty seconds ago. It falls apart the moment you want to review a forty minute agent run from last Tuesday, or compare three runs of the same workflow to see where they diverged.

The core issue is that everything lives inside collapsible panels. Prompts get truncated. Tool call arguments hide behind expanders. Retrieval documents show a preview, and the full text needs another click. If you want to read the trace top to bottom the way you would read a document, you spend more time clicking than reading. Search inside a single trace is limited, and there is no way to add margin notes or highlights that survive past the current browser session.

There is also the offline problem. Traces live in LangSmith's cloud, behind an auth wall and a network round trip. If you are on a plane, on a train with spotty signal, or debugging a customer issue from a coffee shop with captive wifi, you cannot open them. For a tool that captures your production behavior, that is a real limitation. Teams that treat trace review as a serious engineering practice hit this ceiling within a few weeks of adoption.

Export a LangSmith trace to markdown

LangSmith exposes a Python SDK that gives you the full run tree, including every child span with its inputs, outputs, and metadata. The official client docs walk through authentication with an API key. Once you have a client, pulling a single run is one call: client.read_run("your-run-id", load_child_runs=True) returns a run object with a child_runs attribute you can traverse recursively. The load_child_runs flag is the important part, because without it you get the root span and nothing else. That is a common gotcha when people first script against the API, and it silently produces exports that look correct until you notice half the trace is missing.

Each child has its own inputs, outputs, start and end times, and error field. You can filter by span type if you only care about LLM calls or tool calls, but for review the full tree is usually what you want. Keep the traversal small and dumb, because clever code here bites you the first time LangSmith adds a new span type. A recursive function of ten lines is easier to maintain than a class hierarchy that tries to model every possible span shape.

From there, walk the run tree and write each span as a markdown section. Use the span name as an H3, dump the input as a fenced JSON block, the output as another, and any error as a blockquote. If the span is an LLM call, pull the prompt and response into their own sections so they read like a conversation rather than a dictionary dump. Small formatting choices compound: a trace with 200 spans becomes readable or unreadable based on these decisions.

For agent traces with tool calls, render each tool invocation as its own subsection with the tool name, the arguments, and the result. Retrieval spans deserve the same treatment: list the query, then each retrieved document with its score and a short excerpt. The goal is that reading the markdown top to bottom tells the story of the run, without forcing the reader to reconstruct the timeline in their head. Once the export template is right, every future trace slots into the same shape.

What to include in the export, and what to skip

A raw dump of every field in every span produces a wall of JSON nobody will read. Pick the fields that matter for review and cut the rest. Every team that has tried the full dump approach has ended up trimming it within a week. The short list below has held up across dozens of engineering teams, and it is the right default to start from before you customize.

• Span name, start time, duration, and status
• For LLM calls: model, prompt, response, and token usage
• For tool calls: name, arguments, and result
• For retrieval: query, document count, and top document previews

Skip the trace ID, project ID, parent run pointers, and other plumbing unless you are cross referencing runs. Skip the raw serialized chain configuration. If you need those later, the LangSmith dashboard is still there. The point of the markdown export is to give you a readable narrative, not a byte for byte mirror of the underlying database rows.

Add a short header at the top with the run name, total duration, total tokens, and total cost. That single block answers the questions you will ask ninety percent of the time before you dig into any single span. It also makes it trivial to grep a folder of exports for expensive runs or slow runs. If you want a template that already handles all of this, our post on reading AI reasoning traces shares the same structure and is worth borrowing wholesale.

Open the trace in a real markdown reader

Once you have the markdown file, the reader matters more than most people expect. VS Code is fine for a quick look, but it will not render KaTeX in your prompts, does not handle Mermaid diagrams if you ask an LLM to output one, and treats the file like source code rather than a document. Notion imports it but flattens the code block styling and hides the file inside a database view. Obsidian works if you already live there, but the setup cost is real for teammates who do not.

Prism MD was built for exactly this workflow. Drop the markdown in, get typography tuned for long form reading, syntax highlighting that respects the code blocks, KaTeX for any inline math, and Mermaid for any diagrams the agent decided to generate. Traces sync across your devices, so the trace you exported at your desk is on your phone during the commute. If you want the reasoning behind the design choices, our post on why AI-generated markdown deserves better typography walks through the specific tradeoffs.

The offline story matters here more than in most reading contexts. Once a trace is in Prism MD, you can open it on the subway, on a flight, or in a client meeting where the wifi is hostile. That is when careful rereading happens for most people, and it is exactly when the LangSmith dashboard is unavailable. Fixing that mismatch is half the reason this workflow exists in the first place.

A workflow that scales past one trace

If you review traces regularly, script the export. A small CLI that takes a run ID and writes a dated markdown file to a synced folder turns trace review from a chore into a habit. Add a weekly cron that pulls every failed run from the last seven days into a dated folder, and your Monday review becomes reading a stack of documents instead of clicking through a dashboard. The whole script is under a hundred lines once the template is stable.

For team reviews, commit the exported markdown to a git repository. Now traces have version history, code review, and inline comments through your existing PR workflow. It sounds heavy until you try it once, and then it feels obvious. The LangSmith Cookbook has export examples that are a solid starting point for the CLI. Pair it with the patterns in organize AI conversations by project and you have a real archive that outlives any single vendor dashboard.

Frequently asked questions

Does LangSmith have a native markdown export?

Not at the moment. The dashboard offers JSON export for a single run and CSV export for lists of runs, but nothing that produces readable markdown. You have to build it on top of the SDK. The SDK is stable and the run schema is documented, so a one file script gets you most of the way, and the shape rarely changes across LangSmith releases.

Will exporting traces break my data retention or compliance setup?

Exporting a trace pulls the data through your machine, so treat the markdown file with the same care as the trace itself. If your project handles regulated data, keep exports inside your existing secure storage. Prism MD keeps documents in your own synced folder, so you stay inside whatever encryption and access controls you already have. No new vendor sits between you and the trace.

Can I export traces from self-hosted LangSmith?

Yes. The same SDK works against a self-hosted LangSmith instance. Point the client at your internal endpoint with the LANGSMITH_ENDPOINT environment variable and use an API key issued from your instance. Everything else in the workflow is identical, which is a nice property when teams move from cloud to self-hosted mid project.

How large can a trace get before this workflow struggles?

A single agent run with a few thousand spans produces a markdown file in the low megabytes. Prism MD handles that fine. If you routinely produce runs with tens of thousands of spans, split the export by top level chain and read them as separate documents. Nobody reads a ten thousand span trace end to end anyway, and chunking it by subchain matches how the work is structured in the first place.