Configure threads

Many LLM applications have a chatbot-like interface in which the user and the LLM application engage in a multi-turn conversation. In order to track these conversations, you can use threads in LangSmith.

Group traces into threads

To associate traces together into a thread, you need to pass in a special metadata key where the value is the unique identifier for that thread. The key name should be one of:

• session_id
• thread_id
• conversation_id

The value can be any string you want, but we recommend using UUID v7 thread IDs.

The LangSmith SDK exports a uuid7 helper (Python v0.4.43+, JS v0.3.80+):

• Python: from langsmith import uuid7
• JS/TS: import { uuid7 } from 'langsmith'

For instructions, refer to Add metadata and tags to traces.

Important: To ensure filtering and token counting work correctly across your entire thread, you must set the thread metadata (session_id, thread_id, or conversation_id) on all runs, including child runs within a trace.

If child runs don’t have the thread_id metadata, they won’t be included when:

• Filtering runs by thread.
• Calculating token usage for a thread.
• Aggregating costs across a thread.

When creating child runs (e.g., using @traceable for nested functions or creating child spans), ensure you propagate the thread metadata to all child runs.

Example

This example demonstrates how to log and retrieve conversation history using a structured message format to maintain long-running chats.

The example generates a THREAD_ID with uuid7() and passes it via metadata to @traceable, linking every run from that session into the same thread in LangSmith. Conversation history is persisted locally between turns—replace the file-based store with a database or cache in production. The get_chat_history flag controls whether the pipeline continues an existing thread or starts a fresh one:

Python

import os
import json
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

import openai
from langsmith import traceable, Client, uuid7
from langsmith.wrappers import wrap_openai

# Initialize clients
langsmith_client = Client()
client = wrap_openai(openai.Client())

# Configuration
THREAD_ID = str(uuid7())

# Using a local directory to store thread history. For production use, use a persistent storage solution.
THREADS_DIR = os.path.join(os.path.dirname(__file__), "threads")

# gets a history of all LLM calls in the thread to construct conversation history
def get_thread_history(thread_id: str) -> list:
    path = os.path.join(THREADS_DIR, f"{thread_id}.json")
    if not os.path.exists(path):
        return []
    with open(path, "r") as f:
        return json.load(f)

def save_thread_history(thread_id: str, messages: list):
    os.makedirs(THREADS_DIR, exist_ok=True)
    with open(os.path.join(THREADS_DIR, f"{thread_id}.json"), "w") as f:
        json.dump(messages, f, indent=2, default=str)


@traceable(name="Chat Bot", metadata={"thread_id": THREAD_ID})
def chat_pipeline(messages: list, get_chat_history: bool = False):
    # Whether to continue an existing thread or start a new one
    if get_chat_history:
        history_messages = get_thread_history(THREAD_ID)
        # Get existing conversation history and append new messages
        all_messages = history_messages + messages
    else:
        all_messages = messages

    # Invoke the model
    chat_completion = client.chat.completions.create(
        model="gpt-5.4-mini", messages=all_messages
    )

    response_message = chat_completion.choices[0].message
    print("Response from model:", response_message)

    full_conversation = all_messages + [{"role": response_message.role, "content": response_message.content}]
    save_thread_history(THREAD_ID, full_conversation)

    return {"messages": full_conversation}


# Format message
messages = [
    {
        "content": "Hi, my name is Sally",
        "role": "user"
    }
]

# Call the chat pipeline
result = chat_pipeline(messages, get_chat_history=False)

Make the following calls to continue the conversation. By passing get_chat_history=True,/getChatHistory: true, you can continue the conversation from where it left off. This means that the LLM will receive the entire message history and respond to it, instead of just responding to the latest message:

Python

# Format message
messages = [
    {
        "content": "What is my name",
        "role": "user"
    }
]

# Call the chat pipeline
result = chat_pipeline(messages, get_chat_history=True)

Keep the conversation going. Since past messages are included, the LLM will remember the conversation:

Python

# Continue the conversation.
messages = [
    {
        "content": "What was the first message I sent you?",
        "role": "user"
    }
]

chat_pipeline(messages, get_chat_history=True)

View threads

You can view threads by clicking on the Threads tab in any project details page. You will then see a list of all threads, sorted by the most recent activity.

Use Polly in thread views to analyze conversation threads, understand user sentiment, identify pain points, and track whether issues were resolved.

You can then click into a particular thread. This will open the history for a particular thread:

You can view threads in two different ways:

• Thread overview
• Trace view

You can use the buttons at the top of the page to switch between the two views or use the keyboard shortcut T to toggle between the two views.

Thread overview

The thread overview displays each turn of the conversation sequentially, showing the inputs and outputs for each trace in the thread. You can configure which fields in the inputs and outputs are displayed in the overview, or show multiple fields by clicking the Configure button.

The JSON path for the inputs and outputs supports negative indexing, so you can use -1 to access the last element of an array. For example, inputs.messages[-1].content will access the last message in the messages array.

Trace view

The trace view for threads is similar to the trace view when looking at a single run, except that you have access to all the runs for each turn in the thread.

View feedback

When viewing a thread, across the top of the page you will see a section called Feedback. This is where you can review the feedback for each of the runs that make up the thread. This feedback is aggregated, so if you evaluate each run of a thread for the same criteria, you will see the average score across all the displayed runs. You can also see thread-level feedback left here.

Save thread-level filter

Thread filters look through all runs and surface a thread if at least 1 run matches the filter.

Similar to saving filters at the project level, you can also save commonly used filters at the thread level. To save filters on the Threads table, set a filter using the Add filter button and then click the Save view button.

You can open up the trace or annotate the trace in a side panel by clicking on Annotate and Open trace, respectively.

Related

• Observability concepts: background on threads and how they relate to runs and traces.
• Add metadata and tags to traces: how to pass thread_id and other metadata keys.
• Filter traces: filter by thread metadata in the tracing UI.
• Set up multi-turn online evaluators: evaluate threads rather than individual runs.
• Log user feedback using the SDK: attach feedback to runs within a thread.

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.