langsmith 0.10.8 → 0.10.9

package/dist/_openapi_client/resources/threads/threads.d.ts

@@ -0,0 +1,973 @@
+import { APIResource } from '../../core/resource.js';
+import * as ShareAPI from './share.js';
+import { Share, ShareCreateParams, ShareCreateResponse, ShareDeleteParams, ShareRetrieveParams, ShareRetrieveResponse } from './share.js';
+import { APIPromise } from '../../core/api-promise.js';
+import { ItemsCursorGetPagination, type ItemsCursorGetPaginationParams, ItemsCursorPostPagination, type ItemsCursorPostPaginationParams, PagePromise } from '../../core/pagination.js';
+import { RequestOptions } from '../../internal/request-options.js';
+export declare class Threads extends APIResource {
+    share: ShareAPI.Share;
+    /**
+     * 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.
+     *
+     * @example
+     * ```ts
+     * const response = await client.threads.aggregateStats({
+     *   project_id: '0190a1b2-c3d4-7ef0-a5b6-6ea3a82e9328',
+     *   select: [
+     *     'THREAD_COUNT',
+     *     'TRACE_COUNT',
+     *     'TOTAL_TOKENS',
+     *     'TOTAL_COST',
+     *   ],
+     * });
+     * ```
+     */
+    aggregateStats(body: ThreadAggregateStatsParams, options?: RequestOptions): APIPromise<ThreadAggregateStatsResponse>;
+    /**
+     * Retrieve all traces belonging to a specific thread within a project.
+     *
+     * Self-hosted deployments require LangSmith `v0.16` or later.
+     *
+     * @example
+     * ```ts
+     * // Automatically fetches more pages as needed.
+     * for await (const threadTrace of client.threads.listTraces(
+     *   'thread_id',
+     *   { project_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' },
+     * )) {
+     *   // ...
+     * }
+     * ```
+     */
+    listTraces(threadID: string, query: ThreadListTracesParams, options?: RequestOptions): PagePromise<ThreadTracesItemsCursorGetPagination, ThreadTrace>;
+    /**
+     * Query threads within a project (session), with cursor-based pagination. Returns
+     * threads matching the given time range and optional filters.
+     *
+     * Self-hosted deployments require LangSmith `v0.16` or later.
+     *
+     * @example
+     * ```ts
+     * // Automatically fetches more pages as needed.
+     * for await (const thread of client.threads.query()) {
+     *   // ...
+     * }
+     * ```
+     */
+    query(params: ThreadQueryParams, options?: RequestOptions): PagePromise<ThreadsItemsCursorPostPagination, Thread>;
+    /**
+     * 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.
+     *
+     * @example
+     * ```ts
+     * const threadStats = await client.threads.stats(
+     *   'thread_id',
+     *   {
+     *     selects: ['TURNS'],
+     *     session_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+     *   },
+     * );
+     * ```
+     */
+    stats(threadID: string, query: ThreadStatsParams, options?: RequestOptions): APIPromise<ThreadStats>;
+}
+export type ThreadTracesItemsCursorGetPagination = ItemsCursorGetPagination<ThreadTrace>;
+export type ThreadsItemsCursorPostPagination = ItemsCursorPostPagination<Thread>;
+export interface Thread {
+    /**
+     * `count` is how many root traces (conversation turns) fall in this thread for the
+     * query time range.
+     */
+    count?: number;
+    /**
+     * `feedback_stats` is the aggregated feedback across traces in the thread, keyed
+     * by feedback key; shape matches `feedback_stats` on a single run.
+     */
+    feedback_stats?: {
+        [key: string]: Thread.FeedbackStats;
+    };
+    /**
+     * `first_inputs` is a truncated preview of inputs from the earliest trace in the
+     * thread for the query window.
+     */
+    first_inputs?: string;
+    /**
+     * `first_trace_id` is the root trace UUID for the chronologically first trace in
+     * the query time window.
+     */
+    first_trace_id?: 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_error?: string;
+    /**
+     * `last_outputs` is a truncated preview of outputs from the latest trace in the
+     * thread for the query window.
+     */
+    last_outputs?: string;
+    /**
+     * `last_trace_id` is the root trace UUID for the chronologically last trace in the
+     * query time window.
+     */
+    last_trace_id?: string;
+    /**
+     * `latency_p50` is the approximate median end-to-end latency of traces in the
+     * thread, in seconds.
+     */
+    latency_p50?: number;
+    /**
+     * `latency_p99` is the approximate 99th percentile end-to-end latency of traces in
+     * the thread, in seconds.
+     */
+    latency_p99?: number;
+    /**
+     * `max_start_time` is the latest trace start time in the thread (RFC3339
+     * date-time).
+     */
+    max_start_time?: string;
+    /**
+     * `min_start_time` is the earliest trace start time in the thread (RFC3339
+     * date-time).
+     */
+    min_start_time?: string;
+    /**
+     * `num_errored_turns` is the count of root traces in the thread (within the query
+     * window) whose status was an error.
+     */
+    num_errored_turns?: number;
+    /**
+     * `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.
+     */
+    query_metadata?: unknown | null;
+    /**
+     * `start_time` is a reference start time for this row (RFC3339 date-time), such as
+     * for sorting.
+     */
+    start_time?: string;
+    /**
+     * `thread_id` identifies this conversation thread within the project from the
+     * request body `project_id`.
+     */
+    thread_id?: string;
+    /**
+     * `total_cost` is the sum of estimated USD cost across those traces.
+     */
+    total_cost?: number;
+    /**
+     * `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_cost_details?: {
+        [key: string]: number;
+    };
+    /**
+     * `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_token_details?: {
+        [key: string]: number;
+    };
+    /**
+     * `total_tokens` is the sum of token usage across those traces.
+     */
+    total_tokens?: number;
+    /**
+     * `trace_id` is a representative root trace UUID when the summary includes one,
+     * for example for deep links.
+     */
+    trace_id?: string;
+}
+export declare namespace Thread {
+    interface FeedbackStats {
+        /**
+         * `avg` is the arithmetic mean of numeric feedback scores for this key on the run,
+         * or `null` when no numeric score has been recorded (for example purely
+         * categorical feedback).
+         */
+        avg?: number;
+        /**
+         * `comments` is a sample of human-readable comments attached to feedback points
+         * for this key, in no particular order. May be empty; is not exhaustive when many
+         * comments exist.
+         */
+        comments?: Array<string>;
+        /**
+         * `contains_thread_feedback` is true when at least one feedback point for this key
+         * was submitted at the thread level (rather than at an individual run). Always
+         * false on responses that already describe a single run in isolation.
+         */
+        contains_thread_feedback?: boolean;
+        /**
+         * `errors` is the number of feedback points recorded as errors rather than
+         * successful scores (for example an automated evaluator that raised an exception).
+         * Defaults to 0 when no errors occurred.
+         */
+        errors?: number;
+        /**
+         * `max` is the largest numeric feedback score recorded for this key on the run, or
+         * `null` when no numeric score has been recorded.
+         */
+        max?: number;
+        /**
+         * `min` is the smallest numeric feedback score recorded for this key on the run,
+         * or `null` when no numeric score has been recorded.
+         */
+        min?: number;
+        /**
+         * `n` is the number of feedback points recorded for this key on the run. For
+         * numeric feedback this is the sample size behind `avg`, `min`, `max`, and
+         * `stdev`; for categorical feedback it is the sum of the `values` counts.
+         */
+        n?: number;
+        /**
+         * `sources` is a sample of feedback sources for this key. Each entry is either a
+         * plain string identifier (for example `"api"`, `"app"`, `"model"`) or a JSON
+         * object describing a synthetic source (for example
+         * `{"type": "__ls_composite_feedback"}` for a computed aggregate). Clients must
+         * tolerate both shapes.
+         */
+        sources?: Array<unknown>;
+        /**
+         * `stdev` is the sample standard deviation of numeric feedback scores for this key
+         * on the run, or `null` when it cannot be computed (for example fewer than two
+         * numeric scores, or purely categorical feedback).
+         */
+        stdev?: number;
+        /**
+         * `values` is the distribution of categorical feedback labels for this key,
+         * mapping each label to its occurrence count. Empty (`{}`) for purely numeric
+         * feedback.
+         */
+        values?: {
+            [key: string]: number;
+        };
+    }
+}
+export interface ThreadStats {
+    /**
+     * `completion_cost` is the sum of per-trace completion costs across the thread, in
+     * USD. Populated when `COMPLETION_COST` is selected.
+     */
+    completion_cost?: number;
+    /**
+     * `completion_cost_details` is the per-sub-category sum of completion cost details
+     * across the thread. Populated when `COMPLETION_COST_DETAILS` is selected.
+     */
+    completion_cost_details?: ThreadStats.CompletionCostDetails;
+    /**
+     * `completion_token_details` is the per-sub-category sum of completion token
+     * details across the thread. Populated when `COMPLETION_TOKEN_DETAILS` is
+     * selected.
+     */
+    completion_token_details?: ThreadStats.CompletionTokenDetails;
+    /**
+     * `completion_tokens` is the sum of per-trace completion token counts across the
+     * thread. Populated when `COMPLETION_TOKENS` is selected.
+     */
+    completion_tokens?: number;
+    /**
+     * `feedback_stats` aggregates run-level feedback across the thread's traces, keyed
+     * by feedback key. Populated when `FEEDBACK_STATS` is selected.
+     */
+    feedback_stats?: {
+        [key: string]: ThreadStats.FeedbackStats;
+    };
+    /**
+     * `first_start_time` is the earliest trace start time in the thread (RFC3339).
+     * Populated when `FIRST_START_TIME` is selected.
+     */
+    first_start_time?: string;
+    /**
+     * `last_end_time` is the latest trace end time in the thread (RFC3339). Populated
+     * when `LAST_END_TIME` is selected.
+     */
+    last_end_time?: string;
+    /**
+     * `last_start_time` is the latest trace start time in the thread (RFC3339).
+     * Populated when `LAST_START_TIME` is selected.
+     */
+    last_start_time?: string;
+    /**
+     * `latency_p50_seconds` is the approximate p50 of trace latency across the thread,
+     * in seconds. Populated when `LATENCY_P50` is selected.
+     */
+    latency_p50_seconds?: number;
+    /**
+     * `latency_p99_seconds` is the approximate p99 of trace latency across the thread,
+     * in seconds. Populated when `LATENCY_P99` is selected.
+     */
+    latency_p99_seconds?: number;
+    /**
+     * `prompt_cost` is the sum of per-trace prompt costs across the thread, in USD.
+     * Populated when `PROMPT_COST` is selected.
+     */
+    prompt_cost?: number;
+    /**
+     * `prompt_cost_details` is the per-sub-category sum of prompt cost details across
+     * the thread. Populated when `PROMPT_COST_DETAILS` is selected.
+     */
+    prompt_cost_details?: ThreadStats.PromptCostDetails;
+    /**
+     * `prompt_token_details` is the per-sub-category sum of prompt token details
+     * across the thread. Populated when `PROMPT_TOKEN_DETAILS` is selected.
+     */
+    prompt_token_details?: ThreadStats.PromptTokenDetails;
+    /**
+     * `prompt_tokens` is the sum of per-trace prompt token counts across the thread.
+     * Populated when `PROMPT_TOKENS` is selected.
+     */
+    prompt_tokens?: number;
+    /**
+     * `total_cost` is the sum of per-trace total costs across the thread, in USD.
+     * Populated when `TOTAL_COST` is selected.
+     */
+    total_cost?: number;
+    /**
+     * `total_tokens` is the sum of per-trace total token counts across the thread.
+     * Populated when `TOTAL_TOKENS` is selected.
+     */
+    total_tokens?: number;
+    /**
+     * `turns` is the number of distinct traces (turns) in the thread. Populated when
+     * `TURNS` is selected.
+     */
+    turns?: number;
+}
+export declare namespace ThreadStats {
+    /**
+     * `completion_cost_details` is the per-sub-category sum of completion cost details
+     * across the thread. Populated when `COMPLETION_COST_DETAILS` is selected.
+     */
+    interface CompletionCostDetails {
+        /**
+         * `raw` maps each category name to its estimated USD cost.
+         */
+        raw?: {
+            [key: string]: number;
+        };
+    }
+    /**
+     * `completion_token_details` is the per-sub-category sum of completion token
+     * details across the thread. Populated when `COMPLETION_TOKEN_DETAILS` is
+     * selected.
+     */
+    interface CompletionTokenDetails {
+        /**
+         * `raw` maps each category name to its completion-token count.
+         */
+        raw?: {
+            [key: string]: number;
+        };
+    }
+    interface FeedbackStats {
+        /**
+         * `avg` is the arithmetic mean of numeric feedback scores for this key on the run,
+         * or `null` when no numeric score has been recorded (for example purely
+         * categorical feedback).
+         */
+        avg?: number;
+        /**
+         * `comments` is a sample of human-readable comments attached to feedback points
+         * for this key, in no particular order. May be empty; is not exhaustive when many
+         * comments exist.
+         */
+        comments?: Array<string>;
+        /**
+         * `contains_thread_feedback` is true when at least one feedback point for this key
+         * was submitted at the thread level (rather than at an individual run). Always
+         * false on responses that already describe a single run in isolation.
+         */
+        contains_thread_feedback?: boolean;
+        /**
+         * `errors` is the number of feedback points recorded as errors rather than
+         * successful scores (for example an automated evaluator that raised an exception).
+         * Defaults to 0 when no errors occurred.
+         */
+        errors?: number;
+        /**
+         * `max` is the largest numeric feedback score recorded for this key on the run, or
+         * `null` when no numeric score has been recorded.
+         */
+        max?: number;
+        /**
+         * `min` is the smallest numeric feedback score recorded for this key on the run,
+         * or `null` when no numeric score has been recorded.
+         */
+        min?: number;
+        /**
+         * `n` is the number of feedback points recorded for this key on the run. For
+         * numeric feedback this is the sample size behind `avg`, `min`, `max`, and
+         * `stdev`; for categorical feedback it is the sum of the `values` counts.
+         */
+        n?: number;
+        /**
+         * `sources` is a sample of feedback sources for this key. Each entry is either a
+         * plain string identifier (for example `"api"`, `"app"`, `"model"`) or a JSON
+         * object describing a synthetic source (for example
+         * `{"type": "__ls_composite_feedback"}` for a computed aggregate). Clients must
+         * tolerate both shapes.
+         */
+        sources?: Array<unknown>;
+        /**
+         * `stdev` is the sample standard deviation of numeric feedback scores for this key
+         * on the run, or `null` when it cannot be computed (for example fewer than two
+         * numeric scores, or purely categorical feedback).
+         */
+        stdev?: number;
+        /**
+         * `values` is the distribution of categorical feedback labels for this key,
+         * mapping each label to its occurrence count. Empty (`{}`) for purely numeric
+         * feedback.
+         */
+        values?: {
+            [key: string]: number;
+        };
+    }
+    /**
+     * `prompt_cost_details` is the per-sub-category sum of prompt cost details across
+     * the thread. Populated when `PROMPT_COST_DETAILS` is selected.
+     */
+    interface PromptCostDetails {
+        /**
+         * `raw` maps each category name to its estimated USD cost.
+         */
+        raw?: {
+            [key: string]: number;
+        };
+    }
+    /**
+     * `prompt_token_details` is the per-sub-category sum of prompt token details
+     * across the thread. Populated when `PROMPT_TOKEN_DETAILS` is selected.
+     */
+    interface PromptTokenDetails {
+        /**
+         * `raw` maps each category name to its prompt-token count.
+         */
+        raw?: {
+            [key: string]: number;
+        };
+    }
+}
+export interface ThreadTrace {
+    /**
+     * `completion_cost` is the estimated USD cost for the completion. Omitted unless
+     * included in `selects`.
+     */
+    completion_cost?: number;
+    /**
+     * `completion_cost_details` is the USD cost breakdown for completion-side
+     * categories; per-category values are under `raw`. Omitted unless included in
+     * `selects`.
+     */
+    completion_cost_details?: ThreadTrace.CompletionCostDetails;
+    /**
+     * `completion_token_details` is the completion-side token breakdown by category;
+     * per-category counts are under `raw`. Omitted unless included in `selects`.
+     */
+    completion_token_details?: ThreadTrace.CompletionTokenDetails;
+    /**
+     * `completion_tokens` is the completion-side token count. Omitted unless included
+     * in `selects`.
+     */
+    completion_tokens?: number;
+    /**
+     * `end_time` is when the root run ended (RFC3339 date-time). JSON null if the run
+     * is still in progress. Omitted unless included in `selects`.
+     */
+    end_time?: string;
+    /**
+     * `error` is the full root run error message when the run failed. Omitted unless
+     * included in `selects`.
+     */
+    error?: string;
+    /**
+     * `error_preview` is a short error summary when the run failed. Omitted unless
+     * included in `selects`.
+     */
+    error_preview?: string;
+    /**
+     * `first_token_time` is when the first output token was produced (RFC3339
+     * date-time), for streamed runs when that metadata exists. Omitted unless included
+     * in `selects`.
+     */
+    first_token_time?: string;
+    /**
+     * `inputs` is the full root run input payload. Omitted unless included in
+     * `selects`.
+     */
+    inputs?: unknown;
+    /**
+     * `inputs_preview` is a truncated text preview of inputs. Omitted unless included
+     * in `selects`.
+     */
+    inputs_preview?: string;
+    /**
+     * `latency` is wall-clock duration from start to end in seconds. Omitted unless
+     * included in `selects`.
+     */
+    latency?: number;
+    /**
+     * `name` is a human-readable label for the root run (for example the model name,
+     * function name, or step name chosen when the run was traced). Omitted unless
+     * included in `selects`.
+     */
+    name?: string;
+    /**
+     * `op` is a numeric code identifying the root run's `run_type` (for example LLM
+     * vs. tool vs. chain). Encoded as a number for compatibility with legacy clients;
+     * prefer the string `run_type` on `RunResponse` when available. Omitted unless
+     * included in `selects`.
+     */
+    op?: number;
+    /**
+     * `outputs` is the full root run output payload. Omitted unless included in
+     * `selects`.
+     */
+    outputs?: unknown;
+    /**
+     * `outputs_preview` is a truncated text preview of outputs. Omitted unless
+     * included in `selects`.
+     */
+    outputs_preview?: string;
+    /**
+     * `prompt_cost` is the estimated USD cost for the prompt. Omitted unless included
+     * in `selects`.
+     */
+    prompt_cost?: number;
+    /**
+     * `prompt_cost_details` is the USD cost breakdown for prompt-side categories;
+     * per-category values are under `raw`. Omitted unless included in `selects`.
+     */
+    prompt_cost_details?: ThreadTrace.PromptCostDetails;
+    /**
+     * `prompt_token_details` is the prompt-side token breakdown by category;
+     * per-category counts are under nested `raw`. Omitted unless included in
+     * `selects`.
+     */
+    prompt_token_details?: ThreadTrace.PromptTokenDetails;
+    /**
+     * `prompt_tokens` is the prompt-side token count. Omitted unless included in
+     * `selects`.
+     */
+    prompt_tokens?: number;
+    /**
+     * `start_time` is when the trace started (RFC3339 date-time). Omitted unless
+     * included in `selects`.
+     */
+    start_time?: string;
+    /**
+     * `thread_id` is the conversation thread UUID that contains this trace. Matches
+     * the `thread_id` path parameter of the request. Omitted unless included in
+     * `selects`.
+     */
+    thread_id?: string;
+    /**
+     * `total_cost` is the estimated total USD cost for the root run. Omitted unless
+     * included in `selects`.
+     */
+    total_cost?: number;
+    /**
+     * `total_tokens` is the total token count (prompt plus completion). Omitted unless
+     * included in `selects`.
+     */
+    total_tokens?: number;
+    /**
+     * `trace_id` is the UUID of this trace (the root run). Returned when `TRACE_ID` is
+     * in `selects`, or when `selects` is omitted entirely (sole fallback field).
+     */
+    trace_id?: string;
+    /**
+     * `turn_number` is the 1-based position in the whole thread, ordered by start_time
+     * then trace_id ascending, before filtering or pagination. Updates and deletions
+     * can change this position. Omitted unless TURN_NUMBER is included in `selects`.
+     */
+    turn_number?: number;
+}
+export declare namespace ThreadTrace {
+    /**
+     * `completion_cost_details` is the USD cost breakdown for completion-side
+     * categories; per-category values are under `raw`. Omitted unless included in
+     * `selects`.
+     */
+    interface CompletionCostDetails {
+        /**
+         * `raw` maps each category name to its estimated USD cost.
+         */
+        raw?: {
+            [key: string]: number;
+        };
+    }
+    /**
+     * `completion_token_details` is the completion-side token breakdown by category;
+     * per-category counts are under `raw`. Omitted unless included in `selects`.
+     */
+    interface CompletionTokenDetails {
+        /**
+         * `raw` maps each category name to its completion-token count.
+         */
+        raw?: {
+            [key: string]: number;
+        };
+    }
+    /**
+     * `prompt_cost_details` is the USD cost breakdown for prompt-side categories;
+     * per-category values are under `raw`. Omitted unless included in `selects`.
+     */
+    interface PromptCostDetails {
+        /**
+         * `raw` maps each category name to its estimated USD cost.
+         */
+        raw?: {
+            [key: string]: number;
+        };
+    }
+    /**
+     * `prompt_token_details` is the prompt-side token breakdown by category;
+     * per-category counts are under nested `raw`. Omitted unless included in
+     * `selects`.
+     */
+    interface PromptTokenDetails {
+        /**
+         * `raw` maps each category name to its prompt-token count.
+         */
+        raw?: {
+            [key: string]: number;
+        };
+    }
+}
+export interface ThreadAggregateStatsResponse {
+    /**
+     * `completion_cost` is the completion cost across matching traces in USD.
+     */
+    completion_cost?: number;
+    /**
+     * `completion_cost_details` contains completion-cost totals by category.
+     */
+    completion_cost_details?: {
+        [key: string]: number;
+    };
+    /**
+     * `completion_token_details` contains completion-token totals by category.
+     */
+    completion_token_details?: {
+        [key: string]: number;
+    };
+    /**
+     * `completion_tokens` is the sum of completion tokens across matching traces.
+     */
+    completion_tokens?: number;
+    /**
+     * `error_rate` is the fraction of matching traces that contain an error.
+     */
+    error_rate?: number;
+    /**
+     * `first_token_p50_seconds` is the approximate median time to first token in
+     * seconds. Populated when `FIRST_TOKEN_P50` is selected.
+     */
+    first_token_p50_seconds?: number;
+    /**
+     * `first_token_p99_seconds` is the approximate p99 time to first token in seconds.
+     * Populated when `FIRST_TOKEN_P99` is selected.
+     */
+    first_token_p99_seconds?: number;
+    /**
+     * `latency_p50_seconds` is the approximate median trace latency in seconds.
+     * Populated when `LATENCY_P50` is selected.
+     */
+    latency_p50_seconds?: number;
+    /**
+     * `latency_p99_seconds` is the approximate p99 trace latency in seconds. Populated
+     * when `LATENCY_P99` is selected.
+     */
+    latency_p99_seconds?: number;
+    /**
+     * `median_tokens` is the approximate median of total tokens across matching
+     * traces. Populated when `MEDIAN_TOKENS` is selected.
+     */
+    median_tokens?: number;
+    /**
+     * `prompt_cost` is the prompt cost across matching traces in USD.
+     */
+    prompt_cost?: number;
+    /**
+     * `prompt_cost_details` contains prompt-cost totals by category.
+     */
+    prompt_cost_details?: {
+        [key: string]: number;
+    };
+    /**
+     * `prompt_token_details` contains prompt-token totals by category.
+     */
+    prompt_token_details?: {
+        [key: string]: number;
+    };
+    /**
+     * `prompt_tokens` is the sum of prompt tokens across matching traces.
+     */
+    prompt_tokens?: number;
+    /**
+     * `streaming_rate` is the fraction of completed matching traces that streamed
+     * tokens.
+     */
+    streaming_rate?: number;
+    /**
+     * `thread_count` is the number of distinct threads matching the query. Populated
+     * when `THREAD_COUNT` is selected.
+     */
+    thread_count?: number;
+    /**
+     * `thread_feedback_stats` contains aggregate thread-level feedback statistics
+     * keyed by feedback key. Populated when `THREAD_FEEDBACK_STATS` is selected.
+     */
+    thread_feedback_stats?: {
+        [key: string]: ThreadAggregateStatsResponse.ThreadFeedbackStats;
+    };
+    /**
+     * `total_cost` is the total cost across matching traces in USD.
+     */
+    total_cost?: number;
+    /**
+     * `total_tokens` is the sum of all tokens across matching traces.
+     */
+    total_tokens?: number;
+    /**
+     * `trace_count` is the number of traces in the matching threads. Populated when
+     * `TRACE_COUNT` is selected.
+     */
+    trace_count?: number;
+}
+export declare namespace ThreadAggregateStatsResponse {
+    interface ThreadFeedbackStats {
+        /**
+         * `avg` is the arithmetic mean of numeric feedback scores for this key on the run,
+         * or `null` when no numeric score has been recorded (for example purely
+         * categorical feedback).
+         */
+        avg?: number;
+        /**
+         * `comments` is a sample of human-readable comments attached to feedback points
+         * for this key, in no particular order. May be empty; is not exhaustive when many
+         * comments exist.
+         */
+        comments?: Array<string>;
+        /**
+         * `contains_thread_feedback` is true when at least one feedback point for this key
+         * was submitted at the thread level (rather than at an individual run). Always
+         * false on responses that already describe a single run in isolation.
+         */
+        contains_thread_feedback?: boolean;
+        /**
+         * `errors` is the number of feedback points recorded as errors rather than
+         * successful scores (for example an automated evaluator that raised an exception).
+         * Defaults to 0 when no errors occurred.
+         */
+        errors?: number;
+        /**
+         * `max` is the largest numeric feedback score recorded for this key on the run, or
+         * `null` when no numeric score has been recorded.
+         */
+        max?: number;
+        /**
+         * `min` is the smallest numeric feedback score recorded for this key on the run,
+         * or `null` when no numeric score has been recorded.
+         */
+        min?: number;
+        /**
+         * `n` is the number of feedback points recorded for this key on the run. For
+         * numeric feedback this is the sample size behind `avg`, `min`, `max`, and
+         * `stdev`; for categorical feedback it is the sum of the `values` counts.
+         */
+        n?: number;
+        /**
+         * `sources` is a sample of feedback sources for this key. Each entry is either a
+         * plain string identifier (for example `"api"`, `"app"`, `"model"`) or a JSON
+         * object describing a synthetic source (for example
+         * `{"type": "__ls_composite_feedback"}` for a computed aggregate). Clients must
+         * tolerate both shapes.
+         */
+        sources?: Array<unknown>;
+        /**
+         * `stdev` is the sample standard deviation of numeric feedback scores for this key
+         * on the run, or `null` when it cannot be computed (for example fewer than two
+         * numeric scores, or purely categorical feedback).
+         */
+        stdev?: number;
+        /**
+         * `values` is the distribution of categorical feedback labels for this key,
+         * mapping each label to its occurrence count. Empty (`{}`) for purely numeric
+         * feedback.
+         */
+        values?: {
+            [key: string]: number;
+        };
+    }
+}
+export interface ThreadAggregateStatsParams {
+    /**
+     * `project_id` is the tracing project UUID.
+     */
+    project_id: string;
+    /**
+     * `select` lists the aggregate statistics to compute and return. At least one
+     * value is required.
+     */
+    select: Array<'THREAD_COUNT' | 'TRACE_COUNT' | 'TOTAL_TOKENS' | 'TOTAL_COST' | 'ERROR_RATE' | 'STREAMING_RATE' | 'LATENCY_P50' | 'LATENCY_P99' | 'MEDIAN_TOKENS' | 'FIRST_TOKEN_P50' | 'FIRST_TOKEN_P99' | 'PROMPT_TOKENS' | 'COMPLETION_TOKENS' | 'PROMPT_COST' | 'COMPLETION_COST' | 'PROMPT_TOKEN_DETAILS' | 'COMPLETION_TOKEN_DETAILS' | 'PROMPT_COST_DETAILS' | 'COMPLETION_COST_DETAILS' | 'THREAD_FEEDBACK_STATS'>;
+    /**
+     * `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.
+     */
+    filter?: string;
+    /**
+     * `max_start_time` is the exclusive upper bound on thread activity (RFC3339
+     * date-time). Defaults to now (UTC) when omitted.
+     */
+    max_start_time?: string;
+    /**
+     * `min_start_time` is the inclusive lower bound on thread activity (RFC3339
+     * date-time). Defaults to 1 day before now (UTC) when omitted.
+     */
+    min_start_time?: string;
+    /**
+     * `thread_filter` narrows eligible threads using a LangSmith filter expression
+     * evaluated against the complete thread summary.
+     */
+    thread_filter?: string;
+    /**
+     * `trace_filter` narrows eligible threads to those containing a trace whose root
+     * run matches this LangSmith filter expression.
+     */
+    trace_filter?: string;
+    /**
+     * `tree_filter` narrows eligible threads to those containing a matching run
+     * anywhere in a trace tree.
+     */
+    tree_filter?: string;
+}
+export interface ThreadListTracesParams extends ItemsCursorGetPaginationParams {
+    /**
+     * `project_id` is the tracing project UUID (required).
+     */
+    project_id: string;
+    /**
+     * `filter` narrows which traces are returned for this thread, using a LangSmith
+     * filter expression evaluated against each root trace run. For example: eq(status,
+     * "success") or has(tags, "production"). See
+     * https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language
+     * for syntax.
+     */
+    filter?: string;
+    /**
+     * `selects` lists which properties to include on each returned trace (repeatable
+     * query parameter). Accepts any value of the `ThreadTraceSelectField` enum.
+     * Properties not listed are omitted from each trace object; `trace_id` is always
+     * returned.
+     */
+    selects?: Array<'THREAD_ID' | 'TRACE_ID' | 'OP' | 'PROMPT_TOKENS' | 'COMPLETION_TOKENS' | 'TOTAL_TOKENS' | 'START_TIME' | 'END_TIME' | 'LATENCY' | 'FIRST_TOKEN_TIME' | 'INPUTS_PREVIEW' | 'OUTPUTS_PREVIEW' | 'INPUTS' | 'OUTPUTS' | 'ERROR' | 'PROMPT_COST' | 'COMPLETION_COST' | 'TOTAL_COST' | 'PROMPT_TOKEN_DETAILS' | 'COMPLETION_TOKEN_DETAILS' | 'PROMPT_COST_DETAILS' | 'COMPLETION_COST_DETAILS' | 'NAME' | 'ERROR_PREVIEW' | 'TURN_NUMBER'>;
+    /**
+     * `trace_filter` narrows traces by applying a LangSmith filter expression to each
+     * trace's root run.
+     */
+    trace_filter?: string;
+    /**
+     * `tree_filter` narrows traces to those containing at least one run that matches
+     * the LangSmith filter expression.
+     */
+    tree_filter?: string;
+}
+export interface ThreadQueryParams extends ItemsCursorPostPaginationParams {
+    /**
+     * Body param: `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.
+     */
+    filter?: string;
+    /**
+     * Body param: `max_start_time` is the exclusive upper bound on thread activity
+     * (RFC3339 date-time). Defaults to now (UTC) when omitted.
+     */
+    max_start_time?: string;
+    /**
+     * Body param: `min_start_time` is the inclusive lower bound on thread activity
+     * (RFC3339 date-time). Defaults to 1 day before now (UTC) when omitted.
+     */
+    min_start_time?: string;
+    /**
+     * Body param: `project_id` is the tracing project UUID.
+     */
+    project_id?: string;
+    /**
+     * Body param: `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.
+     */
+    thread_filter?: string;
+    /**
+     * Body param: `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.
+     */
+    trace_filter?: string;
+    /**
+     * Body param: `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.
+     */
+    tree_filter?: string;
+    /**
+     * Header param: application/json or text/event-stream
+     */
+    Accept?: string;
+}
+export interface ThreadStatsParams {
+    /**
+     * `selects` lists which aggregate stats to compute and return (repeatable query
+     * parameter). At least one value is required. Accepts any value of
+     * `SingleThreadStatsSelectField`.
+     */
+    selects: Array<'TURNS' | 'FIRST_START_TIME' | 'LAST_START_TIME' | 'LAST_END_TIME' | 'LATENCY_P50' | 'LATENCY_P99' | 'PROMPT_TOKENS' | 'PROMPT_COST' | 'COMPLETION_TOKENS' | 'COMPLETION_COST' | 'TOTAL_TOKENS' | 'TOTAL_COST' | 'PROMPT_TOKEN_DETAILS' | 'COMPLETION_TOKEN_DETAILS' | 'PROMPT_COST_DETAILS' | 'COMPLETION_COST_DETAILS' | 'FEEDBACK_STATS'>;
+    /**
+     * `session_id` is the tracing project (session) UUID (required).
+     */
+    session_id: string;
+    /**
+     * `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.
+     */
+    filter?: string;
+}
+export declare namespace Threads {
+    export { type Thread as Thread, type ThreadStats as ThreadStats, type ThreadTrace as ThreadTrace, type ThreadAggregateStatsResponse as ThreadAggregateStatsResponse, type ThreadTracesItemsCursorGetPagination as ThreadTracesItemsCursorGetPagination, type ThreadsItemsCursorPostPagination as ThreadsItemsCursorPostPagination, type ThreadAggregateStatsParams as ThreadAggregateStatsParams, type ThreadListTracesParams as ThreadListTracesParams, type ThreadQueryParams as ThreadQueryParams, type ThreadStatsParams as ThreadStatsParams, };
+    export { Share as Share, type ShareCreateResponse as ShareCreateResponse, type ShareRetrieveResponse as ShareRetrieveResponse, type ShareCreateParams as ShareCreateParams, type ShareRetrieveParams as ShareRetrieveParams, type ShareDeleteParams as ShareDeleteParams, };
+}