---
title: "Query Thread Traces"
method: GET
path: "/api/v2/threads/{thread_id}/traces"
tags: ["threads"]
---

# Query Thread Traces

`GET /api/v2/threads/{thread_id}/traces`

## Request

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

Retrieve all traces belonging to a specific thread within a project.

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

## Path parameters

- `thread_id` string, required

## Query parameters

- `cursor` string
- `filter` string
- `page_size` integer
- `project_id` string, uuid, required
- `selects` string[]
- `trace_filter` string
- `tree_filter` string

## Response `200`

items and pagination

- ThreadsQueryThreadTracesResponseBody
  - `items` ThreadsThreadTraceListItem[]: `items` is the page of root traces in this thread. Which properties are populated on each trace depends on the `selects` query parameter.
    - `completion_cost` number: `completion_cost` is the estimated USD cost for the completion. Omitted unless included in `selects`.
    - `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. Omitted unless included in `selects`.
    - `end_time` string, date-time: `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`.
    - `error` string: `error` is the full root run error message when the run failed. Omitted unless included in `selects`.
    - `error_preview` string: `error_preview` is a short error summary when the run failed. Omitted unless included in `selects`.
    - `first_token_time` string, date-time: `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`.
    - `inputs` object: `inputs` is the full root run input payload. Omitted unless included in `selects`.
    - `inputs_preview` string: `inputs_preview` is a truncated text preview of inputs. Omitted unless included in `selects`.
    - `latency` number: `latency` is wall-clock duration from start to end in seconds. Omitted unless included in `selects`.
    - `name` string: `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`.
    - `op` number: `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`.
    - `outputs` object: `outputs` is the full root run output payload. Omitted unless included in `selects`.
    - `outputs_preview` string: `outputs_preview` is a truncated text preview of outputs. Omitted unless included in `selects`.
    - `prompt_cost` number: `prompt_cost` is the estimated USD cost for the prompt. Omitted unless included in `selects`.
    - `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. Omitted unless included in `selects`.
    - `start_time` string, date-time: `start_time` is when the trace started (RFC3339 date-time). Omitted unless included in `selects`.
    - `thread_id` string, uuid: `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`.
    - `total_cost` number: `total_cost` is the estimated total USD cost for the root run. Omitted unless included in `selects`.
    - `total_tokens` integer: `total_tokens` is the total token count (prompt plus completion). Omitted unless included in `selects`.
    - `trace_id` string, uuid: `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).
    - `turn_number` integer: `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`.
  - `next_cursor` string: `next_cursor` is the opaque cursor to pass as `cursor` on the next request. Null on the final page.

## Other responses

- `400`: bad request (missing or invalid query parameters)
- `403`: forbidden (insufficient permission)
- `404`: session not found
- `422`: unprocessable entity (e.g. invalid project UUID)
- `501`: V2 filter syntax or TURN_NUMBER is unavailable for this deployment

## Changes

- **2026-10-27** `52b146f318d7`: 4 info
  - removed the non-success response with the status `401`
  - removed the non-success response with the status `500`
  - removed the non-success response with the status `503`
  - removed the non-success response with the status `504`
- **2026-10-16** `1a8ee9358d81`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/langchain-ai/apis/langsmith/changes/api/v2/threads/:thread_id/traces/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)