Threads - Docs

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).

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
Any user feedback attached via the feedback API

User feedback collected through the User Feedback 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

Find every conversation a user had with one agent

Filter by Agent and User. Threads list returns the matching conversations chronologically.

Audit a conversation that received negative feedback

Toggle With feedback and sort by Last activity descending. Open each thread and inspect the feedback annotation per message.

See the trace behind a single message

Open the thread, click the Run link next to the message you care about — that opens the trace detail for the underlying run.

Traces

Underlying chain-of-calls per message.

Event reporting

How chat events are emitted.

Documentation Index

​How threads are built

​What you see per thread

​Drilling into a thread

​Filtering

​Common workflows

​Related resources