If you’re building a conversational agent or any multi-turn application, LangSmith automatically groups your runs into threads. Querying threads lets you replay full conversations, audit agent behavior across sessions, build analytics on conversation length and latency, and feed downstream workflows like fine-tuning and evaluation.
The SDK exposes two methods for working with threads:
| Method | Use when |
|---|
list_threads / listThreads | You want to browse all threads in a project |
read_thread / readThread | You already know the thread ID and need its runs |
How threads work
Each run you create can carry a thread_id in its metadata. LangSmith uses this to group runs into threads. The backend looks for thread_id in metadata (falling back to session_id or conversation_id).
If you’re using a tracing integration, pass thread_id in the run metadata:
from langsmith import traceable
@traceable(metadata={"thread_id": "conv-abc123"})
def my_agent(user_message: str) -> str:
...
List all threads in a project
list_threads / listThreads fetches all threads in a project and groups their runs together. Results are sorted by most recent activity first.
from langsmith import Client
client = Client()
threads = client.list_threads(project_name="my-project")
for thread in threads:
print(thread["thread_id"])
print(f" {thread['count']} runs")
print(f" last active: {thread['max_start_time']}")
conv-abc123
3 runs
last active: 2026-02-25T10:05:42+00:00
conv-def456
1 runs
last active: 2026-02-25T09:30:00+00:00
Parameters
| Parameter | Type | Default | Description |
|---|
project_name / projectName | string | — | Project name. Required if project_id is not set. |
project_id / projectId | string | — | Project ID. Required if project_name is not set. |
limit | int | all | Maximum number of threads to return. |
offset | int | 0 | Number of threads to skip (for pagination). |
filter | string | — | Filter expression applied when fetching runs, using LangSmith trace query syntax. |
start_time / startTime | datetime / Date | 1 day ago | Only include runs started after this time. Widen this window to surface older threads. |
Return value
A list of thread objects, each containing:
| Field | Type | Description |
|---|
thread_id | string | The thread identifier. |
runs | [Run](https://reference.langchain.com/python/langsmith/schemas/Run)[] | Root runs in this thread, sorted chronologically (oldest first). |
count | int | Number of runs in this thread. |
min_start_time | string | null | ISO timestamp of the earliest run. |
max_start_time | string | null | ISO timestamp of the most recent run. |
list_threads always returns root runs only. If you need child runs (e.g., tool calls, sub-chains), use read_thread instead, which accepts an is_root / isRoot parameter you can set to false.
Read runs for a single thread
When you already know the thread_id, use read_thread / readThread. It returns an iterator over the thread’s runs directly, without fetching all threads first.
from langsmith import Client
client = Client()
for run in client.read_thread(
thread_id="conv-abc123",
project_name="my-project",
):
print(run.id, run.name, run.start_time)
list_threads, each item here is a Run object directly — there is no grouping wrapper. Runs are returned in ascending chronological order by default.
[
Run(id=UUID("a1b2..."), name="my_agent", run_type="chain", status="success", start_time=datetime(2026, 2, 25, 10, 0, 0, tzinfo=utc), ...),
Run(id=UUID("c3d4..."), name="my_agent", run_type="chain", status="success", start_time=datetime(2026, 2, 25, 10, 3, 11, tzinfo=utc), ...),
Run(id=UUID("e5f6..."), name="my_agent", run_type="chain", status="error", start_time=datetime(2026, 2, 25, 10, 5, 42, tzinfo=utc), ...),
]
Parameters
| Parameter | Type | Default | Description |
|---|
thread_id / threadId | string | — | Required. The thread to query. |
project_name / projectName | string | — | Project name. Required if project_id is not set. |
project_id / projectId | string | string[] | — | Project ID or list of IDs. Required if project_name is not set. |
is_root / isRoot | bool | true | Return only root runs. Set to false to include child runs. |
limit | int | all | Maximum number of runs to return. |
filter | string | — | Additional filter expression (combined with the thread filter). |
order | "asc" | "desc" | "asc" | Sort order. "asc" returns runs oldest-first (chronological). |
select | string[] | all fields | Specific run fields to return, to reduce response size. |
Return value
An iterator (Python) or async iterator (TypeScript) of Run objects.
Examples
Filter threads by run properties
Pass a filter expression to narrow results using LangSmith trace query syntax. For example, to surface only threads containing at least one failed run:
threads = client.list_threads(
project_name="my-project",
filter='eq(status, "error")',
)
Look back further than 24 hours
By default, list_threads only surfaces threads with runs from the last day. Pass start_time to widen the window:
import datetime
threads = client.list_threads(
project_name="my-project",
start_time=datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=2),
)
Reconstruct a conversation
Use read_thread with order="asc" to replay a conversation turn by turn:
runs = list(
client.read_thread(
thread_id="conv-abc123",
project_name="my-project",
order="asc",
)
)
for run in runs:
user_msg = run.inputs.get("messages", [{}])[-1].get("content", "")
assistant_msg = (run.outputs or {}).get("content", "")
print(f"User: {user_msg}")
print(f"Assistant: {assistant_msg}")
print()
