--- title: "List runs in a trace" method: GET path: "/api/v2/traces/{trace_id}/runs" tags: ["runs"] --- # List runs in a trace `GET /api/v2/traces/{trace_id}/runs` ## Request - Base URL: `https://api.smith.langchain.com` - URL: `https://api.smith.langchain.com/api/v2/traces/{trace_id}/runs` - 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` Returns runs for a trace ID within min/max start time. Optional `filter`; repeatable `selects` to select fields to return. Self-hosted deployments require LangSmith `v0.16` or later. ## Path parameters - `trace_id` string, uuid, required ## Query parameters - `filter` string - `max_start_time` string, date-time - `min_start_time` string, date-time - `project_id` string, uuid, required - `selects` string[] ## Headers - `Accept` string ## Response `200` OK - QueryQueryTraceResponseBody - `items` QueryRunResponse[]: `items` lists runs in the trace for the requested time window, in `start_time` order. - `app_path` string: `app_path` identifies the application code location that produced this run, if recorded. - `attachments` QueryRunAttachmentURLs - `completion_cost` number: `completion_cost` is estimated USD cost for the completion. - `completion_cost_details` QueryRunCompletionCostDetails - `raw` object: `raw` maps each category name to its estimated USD cost. - `completion_token_details` QueryRunCompletionTokenDetails - `raw` object: `raw` maps each category name to its completion-token count. - `completion_tokens` integer: `completion_tokens` is the completion-side token count. - `dotted_order` string: `dotted_order` is the hierarchical ordering key for trace trees. - `end_time` string, date-time: `end_time` is when the run ended (RFC3339 date-time). JSON null if the run has not finished yet. - `error` string: `error` is the error message when `status` indicates failure. - `error_preview` string: `error_preview` is a truncated plain-text error snippet. - `events` QueryRunEvent[]: `events` is the ordered list of run events (for example streaming tokens). - `kwargs` object: `kwargs` is the event payload — an opaque JSON object whose shape depends on `name` and on the emitting SDK. For example LangChain emits `{"token": {...}}` for `new_token` events, tool-call start/end details for tool events, and arbitrary user-defined payloads for custom events. Clients should treat `kwargs` as untyped JSON: do not assume specific keys exist for a given `name`, and tolerate additional unknown keys appearing over time. - `name` string: `name` is the event kind. Common values emitted by the LangChain/LangSmith tracer SDKs include `"start"`, `"end"`, and `"new_token"`, but applications may emit arbitrary strings for their own instrumentation. - `time` string, date-time: `time` is when the event occurred (RFC3339 date-time with millisecond precision). - `extra` object: `extra` is additional runtime JSON attached to the run. - `feedback_stats` QueryRunFeedbackStats - `first_token_time` string, date-time: `first_token_time` is when the first output token was produced (RFC3339 date-time), when recorded for streamed runs. - `id` string, uuid: `id` is this run's UUID. - `inputs` object: `inputs` is the run input payload (arbitrary JSON object). - `inputs_preview` string: `inputs_preview` is a truncated plain-text preview of inputs. - `is_in_dataset` boolean: `is_in_dataset` is true when this run is linked to a dataset example. - `is_root` boolean: `is_root` is true when this run has no parent (it is the trace root). - `last_queued_at` string, date-time: `last_queued_at` is the most recent time this run was added to an annotation queue. - `latency_seconds` number: `latency_seconds` is wall-clock duration from start to end in seconds. - `ls_user_id` string, uuid: `ls_user_id` identifies the LangSmith user whose credential traced the run. It is absent for runs traced with a service-account API key, which has no associated user. - `manifest` object: `manifest` is the serialized configuration of the traced component (for example the model parameters, prompt template, or pipeline definition), when recorded. - `metadata` object: `metadata` is arbitrary user-defined JSON metadata. - `name` string: `name` is a human-readable label for the run (for example the model name, function name, or step name chosen when the run was traced). - `outputs` object: `outputs` is the run output payload (arbitrary JSON object). - `outputs_preview` string: `outputs_preview` is a truncated plain-text preview of outputs. - `parent_run_ids` string[]: `parent_run_ids` lists ancestor run UUIDs from the trace root down to the direct parent. - `price_model_id` string, uuid: `price_model_id` identifies the pricing model UUID used for cost estimates, when recorded. - `project_id` string, uuid: `project_id` is the tracing project UUID this run was logged to. - `prompt_cost` number: `prompt_cost` is estimated USD cost for the prompt. - `prompt_cost_details` QueryRunPromptCostDetails - `raw` object: `raw` maps each category name to its estimated USD cost. - `prompt_token_details` QueryRunPromptTokenDetails - `raw` object: `raw` maps each category name to its prompt-token count. - `prompt_tokens` integer: `prompt_tokens` is the prompt-side token count. - `query_metadata` object, nullable: `query_metadata` describes this query result, including `sem_filter_score` when a semantic filter is used. Returned automatically by run queries, or null when unavailable. - `reference_dataset_id` string, uuid: `reference_dataset_id` is the dataset UUID for the reference example, if any. - `reference_example_id` string, uuid: `reference_example_id` is the dataset example UUID this run was compared against, if any. - `run_type` 'TOOL' | 'CHAIN' | 'LLM' | 'RETRIEVER' | 'EMBEDDING' | 'PROMPT' | 'PARSER' - `share_url` string: `share_url` is the fully-qualified URL of this run's public view, rooted at the deployment's LangSmith app origin (for example `https://smith.langchain.com/public/4f7a1b2c-8d9e-4a0b-9c1d-2e3f4a5b6c7d/r`). It is returned only when `SHARE_URL` is included in `selects`, and only when the run has been explicitly shared; the URL remains stable until the run is unshared. Anyone with this URL can view the run anonymously, so treat it as a secret and do not log it. - `start_time` string, date-time: `start_time` is when the run started (RFC3339 date-time). - `status` 'SUCCESS' | 'ERROR' | 'PENDING' - `tags` string[]: `tags` lists user-defined tags on this run. - `thread_evaluation_time` string, date-time: `thread_evaluation_time` is thread-level evaluation timing (RFC3339 date-time), when recorded. - `thread_id` string, uuid: `thread_id` is the conversation thread UUID this run belongs to, if any. - `total_cost` number: `total_cost` is total estimated USD cost (prompt plus completion). - `total_tokens` integer: `total_tokens` is prompt plus completion tokens. - `trace_id` string, uuid: `trace_id` is the root trace UUID; for a root run it matches `id`. ## Other responses - `400`: bad request (missing or invalid query parameters) - `401`: missing or invalid authentication - `403`: forbidden (insufficient permission) - `404`: session not found - `422`: unprocessable entity (e.g. invalid UUID) - `500`: internal server error - `501`: V2 filter syntax is unavailable for this deployment; use legacy function-style filters or set SMITHDB_QUERY_ENABLED=true - `503`: service unavailable - `504`: gateway timeout or deadline exceeded ## Changes - **2026-10-16** `1a8ee9358d81`: 1 info - endpoint added [Operation history](https://skmtc.dev/langchain-ai/apis/langsmith/changes/api/v2/traces/:trace_id/runs/get.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)