---
title: "Query runs"
method: POST
path: "/api/v2/runs/query"
tags: ["runs"]
---

# Query runs

`POST /api/v2/runs/query`

## Request

- Base URL: `https://api.smith.langchain.com`
- URL: `https://api.smith.langchain.com/api/v2/runs/query`
- 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 a paginated list of runs for the given projects within min/max start_time. Supports filters, cursor pagination, and `selects` to select fields to return.

When `ai_search` is set, `Accept: text/event-stream` is required; requests without it return 406. AI search is unavailable on deployments that route queries to the v1 backend and returns 501 there.

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

## Headers

- `Accept` string
- `Content-Type` string

## Request body

- QueryQueryRunsRequestBody
  - `ai_search` string: `ai_search` is a plain-language criterion evaluated against the messages from the agent trajectory scoped to the run. AND-ed with the ordinary filters. Requires semantic filtering enabled for the deployment. Must contain nonempty text of at most 2000 UTF-8 bytes. Not supported on public dataset queries.
  - `cursor` string: `cursor` is the opaque string from a previous response's `next_cursor`. Treat it as opaque and pass it back unmodified.
  - `filter` string: `filter` narrows results to runs matching this LangSmith filter expression, evaluated against each individual run. For example: and(eq(run_type, "llm"), gt(latency, 5)) or eq(status, "error"). See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax.
  - `has_error` boolean: `has_error` filters to runs that errored (true) or completed without error (false).
  - `ids` string[]: `ids` optionally limits the request to these run UUIDs.
  - `include_subtree_usage` boolean: `include_subtree_usage` enriches selected token and cost fields on root and intermediate runs with subtree totals, and selected `first_token_time` with the earliest observed subtree timestamp. Descendants contribute regardless of this request's filters or time bounds. Runs without observed descendants retain their original values. Defaults to false.
  - `is_root` boolean: `is_root` returns only root runs (true) or only non-root runs (false).
  - `max_feedback_modified_at` string, date-time: `max_feedback_modified_at` is the exclusive upper bound (RFC3339) on feedback `modified_at`, applied to the feedback conditions in `filter`, `trace_filter`, or `tree_filter` (for example eq(feedback_key, "correctness")). Requires at least one feedback condition. Runs must still fall within the `start_time` window.
  - `max_start_time` string, date-time: `max_start_time` is the upper bound for run `start_time` (RFC3339). Defaults to now.
  - `min_feedback_modified_at` string, date-time: `min_feedback_modified_at` is the inclusive lower bound (RFC3339) on feedback `modified_at`, applied to the feedback conditions in `filter`, `trace_filter`, or `tree_filter` (for example eq(feedback_key, "correctness")). Requires at least one feedback condition. Runs must still fall within the `start_time` window.
  - `min_start_time` string, date-time: `min_start_time` is the lower bound for run `start_time` (RFC3339). Defaults to 1 day ago.
  - `page_size` integer: `page_size` is the maximum number of runs to return in this response. Defaults to 100 when omitted; must be between 1 and 1000 inclusive when set.
  - `project_ids` string[]: `project_ids` lists tracing project UUIDs to query. Required unless `reference_dataset_id` is set. Mutually exclusive with `reference_dataset_id` — set exactly one of them.
  - `reference_dataset_id` string, uuid: `reference_dataset_id` resolves session IDs server-side from the dataset. Required unless `project_ids` is set. Mutually exclusive with `project_ids` — set exactly one of them. When provided and `min_start_time` is omitted, the server derives it from the earliest session creation date.
  - `reference_examples` string[]: `reference_examples` optionally limits to runs linked to these dataset example UUIDs.
  - `run_type` 'TOOL' | 'CHAIN' | 'LLM' | 'RETRIEVER' | 'EMBEDDING' | 'PROMPT' | 'PARSER'
  - `selects` QueryRunSelectField[]: `selects` lists which properties to include on each returned run. If omitted, only `id` is returned. Properties not listed are omitted from each run object.
  - `trace_filter` string: `trace_filter` narrows results to runs whose root trace matches this LangSmith filter expression. Use this to filter by properties of the trace's root run — for example eq(status, "success") to include only traces that completed without error. See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax.
  - `trace_id` string, uuid: `trace_id` optionally limits results to runs belonging to this trace UUID.
  - `tree_filter` string: `tree_filter` narrows results to runs that belong to a trace containing at least one run matching this LangSmith filter expression anywhere in the run tree (not just the root). Use this to find runs inside traces that involved a specific tool, tag, or model — for example has(tags, "production") or eq(name, "my_tool"). See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax.

## Response `200`

OK

- QueryQueryRunsResponseBody
  - `items` QueryRunResponse[]: `items` is the page of runs, sorted by `start_time` descending.
    - `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`.
  - `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 (malformed JSON or invalid parameters)
- `401`: missing or invalid authentication
- `403`: forbidden (insufficient permission)
- `404`: session not found
- `406`: not acceptable (ai_search requires Accept: text/event-stream)
- `422`: unprocessable entity (e.g. invalid UUID)
- `500`: internal server error
- `501`: The requested filter syntax or ai_search is unavailable for this deployment
- `503`: service unavailable
- `504`: gateway timeout or deadline exceeded

## Changes

- **2026-10-28** `73dfb1001b4b`: 1 info
  - added the new optional request property `include_subtree_usage`
- **2026-10-16** `1a8ee9358d81`: 1 info
  - endpoint added

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