---
title: "List runs in a trace"
method: GET
path: "/v2/traces/{trace_id}/runs"
tags: ["runs"]
---

# List runs in a trace

`GET /v2/traces/{trace_id}/runs`

**Alpha:** The request and response contract may change;
Returns runs for a trace ID within min/max start time. Optional `filter`; repeatable `selects` to select fields to return.

## Path parameters

- `trace_id` string, uuid, required

## Query parameters

- `filter` string
- `max_start_time` string, date-time, required
- `min_start_time` string, date-time, required
- `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).
    - `latency_seconds` number — `latency_seconds` is wall-clock duration from start to end in seconds.
    - `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.
    - `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
- `503` — service unavailable
- `504` — gateway timeout or deadline exceeded

---

[API](https://skmtc.net/langchain-ai/apis/langsmith.md) · [All operations](https://skmtc.net/langchain-ai/apis/langsmith/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/langchain-ai/langsmith/revisions/a0acb3a6a101/schema)