---
title: "Query Thread Stats"
method: POST
path: "/api/v2/threads/stats"
tags: ["threads"]
---

# Query Thread Stats

`POST /api/v2/threads/stats`

## Request

- Base URL: `https://api.smith.langchain.com`
- URL: `https://api.smith.langchain.com/api/v2/threads/stats`
- 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 aggregate statistics for threads in a tracing project.
The response includes the thread counts, run counts, latency percentiles, rates, token totals, and cost totals requested in `select`.

Self-hosted deployments require LangSmith `v0.17` or later.

## Request body

- ThreadsQueryThreadStatsRequestBody
  - `filter` string: `filter` is a deprecated, unscoped LangSmith filter expression evaluated against trace root runs. Kept for compatibility with deployments that serve this endpoint via the legacy ClickHouse backend (no SmithDB query service configured); prefer `trace_filter`, `tree_filter`, or `thread_filter` otherwise, since those require SmithDB.
  - `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.
  - `project_id` string, uuid, required: `project_id` is the tracing project UUID.
  - `select` ThreadsThreadStatsSelectField[], required: `select` lists the aggregate statistics to compute and return. At least one value is required.
  - `thread_filter` string: `thread_filter` narrows eligible threads using a LangSmith filter expression evaluated against the complete thread summary.
  - `trace_filter` string: `trace_filter` narrows eligible threads to those containing a trace whose root run matches this LangSmith filter expression.
  - `tree_filter` string: `tree_filter` narrows eligible threads to those containing a matching run anywhere in a trace tree.

## Response `200`

aggregate thread statistics

- ThreadsQueryThreadStatsResponseBody
  - `completion_cost` number: `completion_cost` is the completion cost across matching traces in USD.
  - `completion_cost_details` object: `completion_cost_details` contains completion-cost totals by category.
  - `completion_token_details` object: `completion_token_details` contains completion-token totals by category.
  - `completion_tokens` integer: `completion_tokens` is the sum of completion tokens across matching traces.
  - `error_rate` number: `error_rate` is the fraction of matching traces that contain an error.
  - `first_token_p50_seconds` number: `first_token_p50_seconds` is the approximate median time to first token in seconds. Populated when `FIRST_TOKEN_P50` is selected.
  - `first_token_p99_seconds` number: `first_token_p99_seconds` is the approximate p99 time to first token in seconds. Populated when `FIRST_TOKEN_P99` is selected.
  - `latency_p50_seconds` number: `latency_p50_seconds` is the approximate median trace latency in seconds. Populated when `LATENCY_P50` is selected.
  - `latency_p99_seconds` number: `latency_p99_seconds` is the approximate p99 trace latency in seconds. Populated when `LATENCY_P99` is selected.
  - `median_tokens` integer: `median_tokens` is the approximate median of total tokens across matching traces. Populated when `MEDIAN_TOKENS` is selected.
  - `prompt_cost` number: `prompt_cost` is the prompt cost across matching traces in USD.
  - `prompt_cost_details` object: `prompt_cost_details` contains prompt-cost totals by category.
  - `prompt_token_details` object: `prompt_token_details` contains prompt-token totals by category.
  - `prompt_tokens` integer: `prompt_tokens` is the sum of prompt tokens across matching traces.
  - `streaming_rate` number: `streaming_rate` is the fraction of completed matching traces that streamed tokens.
  - `thread_count` integer: `thread_count` is the number of distinct threads matching the query. Populated when `THREAD_COUNT` is selected.
  - `thread_feedback_stats` QueryRunFeedbackStats
  - `total_cost` number: `total_cost` is the total cost across matching traces in USD.
  - `total_tokens` integer: `total_tokens` is the sum of all tokens across matching traces.
  - `trace_count` integer: `trace_count` is the number of traces in the matching threads. Populated when `TRACE_COUNT` is selected.

## 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`: SmithDB query is unavailable for this deployment

## Changes

- **2026-10-16** `1a8ee9358d81`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/langchain-ai/apis/langsmith/changes/api/v2/threads/stats/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)