Skip to main content
When building chatbots or multi-turn agents, each user message creates a separate trace. To group these traces into a single conversation, set the thread_id metadata on each trace.

​
Setting the thread_id

Inside any @langwatch.trace() function, use langwatch.get_current_trace().update(): 
import langwatch

@langwatch.trace()
def handle_message(thread_id: str, user_id: str, message: str):
    langwatch.get_current_trace().update(metadata={
        "thread_id": thread_id,
        "user_id": user_id,
    })

    # your LLM pipeline logic here...
All traces that share the same thread_id will be grouped into a single conversation thread in the LangWatch dashboard.

​
Example: FastAPI Chatbot

import langwatch
from fastapi import FastAPI
from openai import OpenAI
from pydantic import BaseModel

langwatch.setup()

app = FastAPI()
client = OpenAI()

class ChatRequest(BaseModel):
    thread_id: str
    user_id: str
    message: str

@app.post("/chat")
@langwatch.trace()
async def chat(request: ChatRequest):
    langwatch.get_current_trace().update(metadata={
        "thread_id": request.thread_id,
        "user_id": request.user_id,
    })

    # Fetch conversation history from your database using request.thread_id
    history = get_conversation_history(request.thread_id)

    response = client.chat.completions.create(
        model="gpt-4.1",
        messages=[*history, {"role": "user", "content": request.message}],
    )

    return {"reply": response.choices[0].message.content}
The thread_id is typically the conversation or session ID from your application. It can be any string, as long as it’s consistent across all messages in the same conversation.

​
What You Get

Once traces share a thread_id, you can:
  • View the full conversation in the LangWatch dashboard by clicking on any trace in the thread
  • Run evaluations by thread to assess conversation-level quality (see Evaluation by Thread)
  • Build datasets from threads for testing multi-turn scenarios (see Dataset Threads)
  • Filter and search traces by conversation in the messages view