threads

Query Thread Stats

Changed on

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.

post/api/v2/threads/stats

Request

  • Base URL
    https://api.smith.langchain.com
  • URL
    https://api.smith.langchain.com/api/v2/threads/stats
  • Auth
    • API key in header X-API-Key and API key in header X-Tenant-Id
    • or HTTP bearer and API key in header X-Tenant-Id

Request body

filterstring

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_timestring date-time

max_start_time is the exclusive upper bound on thread activity (RFC3339 date-time). Defaults to now (UTC) when omitted.

min_start_timestring 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_idstring uuid required

project_id is the tracing project UUID.

selectThreadsThreadStatsSelectField[] required

select lists the aggregate statistics to compute and return. At least one value is required.

thread_filterstring

thread_filter narrows eligible threads using a LangSmith filter expression evaluated against the complete thread summary.

trace_filterstring

trace_filter narrows eligible threads to those containing a trace whose root run matches this LangSmith filter expression.

tree_filterstring

tree_filter narrows eligible threads to those containing a matching run anywhere in a trace tree.

Example request

{
  "filter": "eq(status, \"error\")",
  "project_id": "0190a1b2-c3d4-7ef0-a5b6-6ea3a82e9328",
  "select": [
    "THREAD_COUNT",
    "TRACE_COUNT",
    "TOTAL_TOKENS",
    "TOTAL_COST"
  ],
  "thread_filter": "gte(turn_count, 3)",
  "trace_filter": "eq(status, \"error\")",
  "tree_filter": "has(tags, \"production\")"
}

Response

aggregate thread statistics

completion_costnumber

completion_cost is the completion cost across matching traces in USD.

completion_cost_detailsobject

completion_cost_details contains completion-cost totals by category.

completion_token_detailsobject

completion_token_details contains completion-token totals by category.

completion_tokensinteger

completion_tokens is the sum of completion tokens across matching traces.

error_ratenumber

error_rate is the fraction of matching traces that contain an error.

first_token_p50_secondsnumber

first_token_p50_seconds is the approximate median time to first token in seconds. Populated when FIRST_TOKEN_P50 is selected.

first_token_p99_secondsnumber

first_token_p99_seconds is the approximate p99 time to first token in seconds. Populated when FIRST_TOKEN_P99 is selected.

latency_p50_secondsnumber

latency_p50_seconds is the approximate median trace latency in seconds. Populated when LATENCY_P50 is selected.

latency_p99_secondsnumber

latency_p99_seconds is the approximate p99 trace latency in seconds. Populated when LATENCY_P99 is selected.

median_tokensinteger

median_tokens is the approximate median of total tokens across matching traces. Populated when MEDIAN_TOKENS is selected.

prompt_costnumber

prompt_cost is the prompt cost across matching traces in USD.

prompt_cost_detailsobject

prompt_cost_details contains prompt-cost totals by category.

prompt_token_detailsobject

prompt_token_details contains prompt-token totals by category.

prompt_tokensinteger

prompt_tokens is the sum of prompt tokens across matching traces.

streaming_ratenumber

streaming_rate is the fraction of completed matching traces that streamed tokens.

thread_countinteger

thread_count is the number of distinct threads matching the query. Populated when THREAD_COUNT is selected.

thread_feedback_statsQueryRunFeedbackStats
total_costnumber

total_cost is the total cost across matching traces in USD.

total_tokensinteger

total_tokens is the sum of all tokens across matching traces.

trace_countinteger

trace_count is the number of traces in the matching threads. Populated when TRACE_COUNT is selected.

Changes