--- title: "Query Threads" method: POST path: "/api/v2/threads/query" tags: ["threads"] --- # Query Threads `POST /api/v2/threads/query` ## Request - Base URL: `https://api.smith.langchain.com` - URL: `https://api.smith.langchain.com/api/v2/threads/query` - Auth: one of: - API key in header `X-API-Key` and API key in header `X-Tenant-Id` - HTTP bearer and API key in header `X-Tenant-Id` GET with body payload — no resources created. Returns the threads in a tracing project matching the query passed as the request payload. Results are filtered by the given time range and optional filters, with cursor-based pagination. When `ai_search` is set, `Accept: text/event-stream` is required; requests without it return 406. AI search is unavailable on deployments that route queries to the v1 backend and returns 501 there. Self-hosted deployments require LangSmith `v0.16` or later. ## Headers - `Accept` string ## Request body - ThreadsQueryThreadsRequestBody - `ai_search` string: `ai_search` is a plain-language criterion evaluated against the messages from the agent trajectory scoped to the thread. AND-ed with the ordinary filters. Requires semantic filtering enabled for the deployment. Must contain nonempty text of at most 2000 UTF-8 bytes. - `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 exclusive upper bound on thread activity (RFC3339 date-time). Defaults to now (UTC) when omitted. - `min_start_time` string, date-time: `min_start_time` is the inclusive lower bound on thread activity (RFC3339 date-time). Defaults to 1 day before now (UTC) when omitted. - `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 non-null. - `project_id` string, uuid: `project_id` is the tracing project UUID. - `thread_filter` string: `thread_filter` narrows results using a LangSmith filter expression evaluated against each complete thread summary. Self-hosted deployments require LangSmith v0.17 or later; unsupported deployments return 501. See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax. - `trace_filter` string: `trace_filter` narrows results to threads containing at least one trace whose root run matches this LangSmith filter expression. Trace-level aggregate fields are evaluated using the complete trace summary. Self-hosted deployments require LangSmith v0.17 or later; unsupported deployments return 501. See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax. - `tree_filter` string: `tree_filter` narrows results to threads containing at least one trace with a matching run anywhere in its run tree. Self-hosted deployments require LangSmith v0.17 or later; unsupported deployments return 501. See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax. ## 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. - `query_metadata` object, nullable: `query_metadata` describes why this thread matched the query, including `sem_filter_score` when a semantic filter is used. Returned automatically, or null when unavailable. - `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. Null on the final page. ## Other responses - `400`: bad request (malformed JSON or invalid parameters) - `403`: forbidden (insufficient permission) - `404`: session not found - `422`: unprocessable entity (e.g. invalid project UUID) - `501`: V2 filter syntax, thread_filters, or ai_search are unavailable for this deployment; use legacy function-style filters without thread_filters or set SMITHDB_QUERY_ENABLED=true ## Changes - **2026-10-27** `52b146f318d7`: 5 info - removed the non-success response with the status `401` - removed the non-success response with the status `406` - removed the non-success response with the status `500` - removed the non-success response with the status `503` - …1 more - **2026-10-16** `1a8ee9358d81`: 1 info - endpoint added [Operation history](https://skmtc.dev/langchain-ai/apis/langsmith/changes/api/v2/threads/query/post.md) --- [API](https://skmtc.dev/langchain-ai/apis/langsmith.md) - [All operations](https://skmtc.dev/langchain-ai/apis/langsmith/llms.txt) - [OpenAPI document](https://skmtc.dev/langchain-ai/apis/langsmith/revisions/7a01c01f75e8?raw)