threads

Query Single Thread Stats

Changed on

Compute aggregate stats for a single thread (turn count, latency percentiles, token/cost sums, and detail breakdowns) within a project.

Self-hosted deployments require LangSmith v0.16 or later.

get/api/v2/threads/{thread_id}/stats

Request

  • Base URL
    https://api.smith.langchain.com
  • URL
    https://api.smith.langchain.com/api/v2/threads/{thread_id}/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

Path parameters

thread_idstring required

Thread ID

Query parameters

filterstring

filter narrows which of the thread's traces are aggregated, using a LangSmith filter expression. For example: lt(start_time, "2025-01-01T00:00:00Z") or eq(trace_id, "0190a1b2-c3d4-7ef0-a5b6-6ea3a82e9328"). See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax.

selectsstring[] required

selects lists which aggregate stats to compute and return (repeatable query parameter). At least one value is required. Accepts any value of SingleThreadStatsSelectField.

session_idstring uuid required

session_id is the tracing project (session) UUID (required).

Response

aggregate stats for the thread

completion_costnumber

completion_cost is the sum of per-trace completion costs across the thread, in USD. Populated when COMPLETION_COST is selected.

completion_tokensinteger

completion_tokens is the sum of per-trace completion token counts across the thread. Populated when COMPLETION_TOKENS is selected.

feedback_statsQueryRunFeedbackStats
first_start_timestring date-time

first_start_time is the earliest trace start time in the thread (RFC3339). Populated when FIRST_START_TIME is selected.

last_end_timestring date-time

last_end_time is the latest trace end time in the thread (RFC3339). Populated when LAST_END_TIME is selected.

last_start_timestring date-time

last_start_time is the latest trace start time in the thread (RFC3339). Populated when LAST_START_TIME is selected.

latency_p50_secondsnumber

latency_p50_seconds is the approximate p50 of trace latency across the thread, in seconds. Populated when LATENCY_P50 is selected.

latency_p99_secondsnumber

latency_p99_seconds is the approximate p99 of trace latency across the thread, in seconds. Populated when LATENCY_P99 is selected.

prompt_costnumber

prompt_cost is the sum of per-trace prompt costs across the thread, in USD. Populated when PROMPT_COST is selected.

prompt_tokensinteger

prompt_tokens is the sum of per-trace prompt token counts across the thread. Populated when PROMPT_TOKENS is selected.

total_costnumber

total_cost is the sum of per-trace total costs across the thread, in USD. Populated when TOTAL_COST is selected.

total_tokensinteger

total_tokens is the sum of per-trace total token counts across the thread. Populated when TOTAL_TOKENS is selected.

turnsinteger

turns is the number of distinct traces (turns) in the thread. Populated when TURNS is selected.

Changes