---
title: "Query Threads"
method: POST
path: "/v2/threads/query"
tags: ["threads"]
---

# Query Threads

`POST /v2/threads/query`

**Alpha:** The request and response contract may change;
Query threads within a project (session), with cursor-based pagination.
Returns threads matching the given time range and optional filter.

## Request body

- ThreadsQueryThreadsRequestBody
  - `cursor` string — `cursor` is the opaque string from a previous response's `next_cursor`. Omit on the first request; pass the returned cursor to fetch the next page.
  - `filter` string — `filter` narrows which threads are returned, using a LangSmith filter expression evaluated against each thread's root run. For example: has(tags, "production") or eq(status, "error"). See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax.
  - `max_start_time` string, date-time — `max_start_time` is the inclusive upper bound on thread activity (RFC3339 date-time).
  - `min_start_time` string, date-time — `min_start_time` is the inclusive lower bound on thread activity (RFC3339 date-time).
  - `page_size` integer — `page_size` is the maximum number of threads to return in this response. Defaults to 20 when omitted; must be between 1 and 100 inclusive when set. The response may contain fewer threads than `page_size` even when `next_cursor` is present.
  - `project_id` string, uuid — `project_id` is the tracing project UUID.

## Response `200`

items and pagination

- ThreadsQueryThreadsResponseBody
  - `items` ThreadsThreadListItem[] — `items` is the page of thread summaries, sorted by the thread's most recent activity.
    - `count` integer — `count` is how many root traces (conversation turns) fall in this thread for the query time range.
    - `feedback_stats` QueryRunFeedbackStats
    - `first_inputs` string — `first_inputs` is a truncated preview of inputs from the earliest trace in the thread for the query window.
    - `first_trace_id` string, uuid — `first_trace_id` is the root trace UUID for the chronologically first trace in the query time window.
    - `last_error` string — `last_error` is a short error summary from the most recent failing trace in the thread. Absent when there is no error in the window.
    - `last_outputs` string — `last_outputs` is a truncated preview of outputs from the latest trace in the thread for the query window.
    - `last_trace_id` string, uuid — `last_trace_id` is the root trace UUID for the chronologically last trace in the query time window.
    - `latency_p50` number — `latency_p50` is the approximate median end-to-end latency of traces in the thread, in seconds.
    - `latency_p99` number — `latency_p99` is the approximate 99th percentile end-to-end latency of traces in the thread, in seconds.
    - `max_start_time` string, date-time — `max_start_time` is the latest trace start time in the thread (RFC3339 date-time).
    - `min_start_time` string, date-time — `min_start_time` is the earliest trace start time in the thread (RFC3339 date-time).
    - `num_errored_turns` integer — `num_errored_turns` is the count of root traces in the thread (within the query window) whose status was an error.
    - `start_time` string, date-time — `start_time` is a reference start time for this row (RFC3339 date-time), such as for sorting.
    - `thread_id` string, uuid — `thread_id` identifies this conversation thread within the project from the request body `project_id`.
    - `total_cost` number — `total_cost` is the sum of estimated USD cost across those traces.
    - `total_cost_details` object — `total_cost_details` sums per-category estimated USD cost across traces in the thread. Keys mirror `total_token_details`. Example: `{"cache_read": 0.012, "reasoning": 0.008}`.
    - `total_token_details` object — `total_token_details` sums per-category token counts across traces in the thread. Keys are model-specific category names (for example `cache_read`, `cache_write`, `reasoning`, `audio`). Example: `{"cache_read": 400, "reasoning": 120}`.
    - `total_tokens` integer — `total_tokens` is the sum of token usage across those traces.
    - `trace_id` string, uuid — `trace_id` is a representative root trace UUID when the summary includes one, for example for deep links.
  - `next_cursor` string — `next_cursor` is the opaque cursor to pass as `cursor` on the next request. Omitted on the final page.

## Other responses

- `400` — bad request (malformed JSON or invalid parameters)
- `401` — missing or invalid authentication
- `403` — forbidden (insufficient permission)
- `404` — session not found
- `422` — unprocessable entity (e.g. invalid project UUID)
- `500` — internal server error
- `503` — service unavailable
- `504` — gateway timeout or deadline exceeded

---

[API](https://skmtc.net/langchain-ai/apis/langsmith.md) · [All operations](https://skmtc.net/langchain-ai/apis/langsmith/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/langchain-ai/langsmith/revisions/a0acb3a6a101/schema)