Skip to main content
The RunTree class provides a low-level API for creating and managing trace trees. While traceable() is recommended for most use cases, RunTree gives you fine-grained control over trace creation.

​
Constructor

import { RunTree } from "langsmith";

const run = new RunTree({
  name: "my-chain",
  run_type: "chain",
  inputs: { query: "Hello" },
  project_name: "my-project",
});
​
config
RunTreeConfig
required
Configuration for the run tree
​
name
string
required
A human-readable name for the run.
​
run_type
string
required
The type of run (e.g., “llm”, “chain”, “tool”, “retriever”).
​
inputs
KVMap
The inputs that were used to initiate the run.
​
id
string
Unique identifier for the run. Auto-generated if not provided.
​
project_name
string
The name of the project/session.
​
parent_run
RunTree
Parent run tree if this is a child run.
​
client
Client
Custom LangSmith client instance.
​
tracingEnabled
boolean
Whether tracing is enabled.
​
tags
string[]
Tags for categorizing the run.
​
metadata
Record<string, any>
Metadata to attach to the run.
​
reference_example_id
string
ID of an example that might be related to this run.

​
Properties

​
id
string
Unique identifier for the run.
​
name
string
The name of the run.
​
run_type
string
The type of run.
​
inputs
KVMap
The run’s inputs.
​
outputs
KVMap
The run’s outputs.
​
error
string
Error message if the run failed.
​
trace_id
string
The ID of the root trace.
​
dotted_order
string
The dotted order for the run (used for sorting).

​
Methods

​
postRun()

Post the run to LangSmith (send the initial run creation). 
await run.postRun();

​
end()

End the run and send the final update to LangSmith. 
await run.end({ response: "Hello!" });
​
outputs
KVMap
The outputs to attach to the run.
​
error
string
Error message if the run failed.

​
patchRun()

Update the run in LangSmith. 
await run.patchRun();

​
createChild()

Create a child run. 
const childRun = run.createChild({
  name: "child-run",
  run_type: "llm",
  inputs: { prompt: "Hello" },
});
​
config
RunTreeConfig
required
Configuration for the child run.
​
RunTree
RunTree
The child run tree.

​
addEvent()

Add an event to the run (e.g., for streaming tokens). 
run.addEvent({
  name: "new_token",
  kwargs: { token: "Hello" },
});

​
addMetadata()

Add metadata to the run. 
run.addMetadata({ key: "value" });

​
addTags()

Add tags to the run. 
run.addTags(["tag1", "tag2"]);

​
Example usage

​
Basic usage

import { RunTree } from "langsmith";

const run = new RunTree({
  name: "my-chain",
  run_type: "chain",
  inputs: { query: "What is LangSmith?" },
  project_name: "my-project",
});

await run.postRun();

try {
  // Do work
  const result = "LangSmith is an observability platform";
  
  await run.end({ response: result });
} catch (error) {
  await run.end(undefined, String(error));
}

​
Nested runs

const parentRun = new RunTree({
  name: "parent-chain",
  run_type: "chain",
  inputs: { query: "Hello" },
});

await parentRun.postRun();

const childRun = parentRun.createChild({
  name: "llm-call",
  run_type: "llm",
  inputs: { prompt: "Hello" },
});

await childRun.postRun();
await childRun.end({ response: "Hi!" });

await parentRun.end({ response: "Hi!" });

​
With streaming

const run = new RunTree({
  name: "streaming-llm",
  run_type: "llm",
  inputs: { prompt: "Tell me a story" },
});

await run.postRun();

const chunks: string[] = [];
for await (const chunk of streamingResponse) {
  chunks.push(chunk);
  run.addEvent({
    name: "new_token",
    kwargs: { token: chunk },
  });
}

await run.end({ response: chunks.join("") });

​
Static methods

​
fromRunnableConfig()

Create a RunTree from a LangChain RunnableConfig. 
const run = RunTree.fromRunnableConfig(runnableConfig, extraConfig);

​
When to use RunTree vs traceable()

Use RunTree when you need:
  • Fine-grained control over when runs are posted/updated
  • To manually manage the trace tree structure
  • To integrate with non-async code
  • To add events during streaming
Use traceable() when:
  • You want automatic trace management
  • You’re wrapping functions
  • You want cleaner code with decorators
  • AsyncLocalStorage works in your environment

Build docs developers (and LLMs) love

Get started for freeTalk to us