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

# Threads

> Multi-turn conversations grouped from chat events, with per-message latency, cost, and feedback.

Threads group runs that share a conversational context, so you can review a multi-turn dialogue end-to-end instead of jumping between isolated runs.

***

## How threads are built

A thread is constructed from events with name `chat`. The SDK groups consecutive `chat` events that share the same `thread_id` (or, when none is supplied, the same agent and user within a time window).

```python theme={"system"}
from flowxobservatory import track_event

track_event(
    "chat",
    role="user",
    content="What's my policy number?",
    thread_id="cust-42",
)
```

Each emitted `chat` event becomes one `ThreadMessage`. The aggregate `Thread` record carries:

* `started_at`, `ended_at`, `message_count`
* Total tokens and total cost across the thread
* Last message preview for the thread list

***

## What you see per thread

| Field             | Meaning                                     |
| ----------------- | ------------------------------------------- |
| **Thread**        | A short preview of the most recent message. |
| **Agent**         | The agent handling the conversation.        |
| **User**          | The user the conversation belongs to.       |
| **Messages**      | Total number of messages so far.            |
| **Tokens**        | Sum of all message tokens.                  |
| **Cost**          | Sum of cost across all messages.            |
| **Last activity** | When the most recent message landed.        |

***

## Drilling into a thread

Click any thread row to open the full conversation. Each message exposes:

* The full `content`
* Per-message latency
* The associated run, with a link out to the [trace](./traces)
* Any user feedback attached via the feedback API

User feedback collected through the [User Feedback](../governance/overview) flow is rendered inline next to the corresponding assistant message.

***

## Filtering

| Filter            | What it does                                              |
| ----------------- | --------------------------------------------------------- |
| **Agent**         | Scope to one agent.                                       |
| **User**          | Scope to one user.                                        |
| **With feedback** | Show only threads that have at least one feedback record. |
| **Time range**    | Standard time selector.                                   |

***

## Common workflows

<AccordionGroup>
  <Accordion title="Find every conversation a user had with one agent" icon="circle-question">
    Filter by **Agent** and **User**. Threads list returns the matching conversations chronologically.
  </Accordion>

  <Accordion title="Audit a conversation that received negative feedback" icon="circle-question">
    Toggle **With feedback** and sort by **Last activity** descending. Open each thread and inspect the feedback annotation per message.
  </Accordion>

  <Accordion title="See the trace behind a single message" icon="circle-question">
    Open the thread, click the **Run** link next to the message you care about — that opens the trace detail for the underlying run.
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup cols={2}>
  <Card title="Traces" icon="bars-staggered" href="./traces">
    Underlying chain-of-calls per message.
  </Card>

  <Card title="Event reporting" icon="paper-plane" href="../sdk/event-reporting">
    How `chat` events are emitted.
  </Card>
</CardGroup>