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

# Tracking Conversations

> Group related traces into conversations using thread_id so you can view and evaluate entire chat sessions in LangWatch.

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()`:

```python theme={null}
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

```python theme={null}
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](/evaluations/online-evaluation/by-thread))
* **Build datasets from threads** for testing multi-turn scenarios (see [Dataset Threads](/datasets/dataset-threads))
* **Filter and search** traces by conversation in the messages view