query_v2

Parameters

Name	Type	Description
`ai_search`	`str \| Omit`	Default:`omit` `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`	`str \| Omit`	Default:`omit` `cursor` is the opaque string from a previous response's `next_cursor`. Treat it as opaque and pass it back unmodified.
`filter`	`str \| Omit`	Default:`omit`
`has_error`	`bool \| Omit`	Default:`omit`
`ids`	`SequenceNotStr[str] \| Omit`	Default:`omit`
`include_subtree_usage`	`bool \| Omit`	Default:`omit`
`is_root`	`bool \| Omit`	Default:`omit`
`max_feedback_modified_at`	`Union[str, datetime] \| Omit`	Default:`omit`
`max_start_time`	`Union[str, datetime] \| Omit`	Default:`omit`
`min_feedback_modified_at`	`Union[str, datetime] \| Omit`	Default:`omit`
`min_start_time`	`Union[str, datetime] \| Omit`	Default:`omit`
`page_size`	`int \| Omit`	Default:`omit`
`project_ids`	`SequenceNotStr[str] \| Omit`	Default:`omit`
`reference_dataset_id`	`str \| Omit`	Default:`omit`
`reference_examples`	`SequenceNotStr[str] \| Omit`	Default:`omit`
`run_type`	`RunType \| Omit`	Default:`omit`
`selects`	`List[RunSelectField] \| Omit`	Default:`omit`
`trace_filter`	`str \| Omit`	Default:`omit`
`trace_id`	`str \| Omit`	Default:`omit`
`tree_filter`	`str \| Omit`	Default:`omit`
`extra_headers`	`Headers \| None`	Default:`None`
`extra_query`	`Query \| None`	Default:`None`
`extra_body`	`Body \| None`	Default:`None`
`timeout`	`float \| httpx.Timeout \| None \| NotGiven`	Default:`not_given`

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.

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 filters to runs that errored (true) or completed without error (false).

ids optionally limits the request to these run UUIDs.

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 returns only root runs (true) or only non-root runs (false).

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 is the upper bound for run start_time (RFC3339). Defaults to now.

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 is the lower bound for run start_time (RFC3339). Defaults to 1 day ago.

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 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 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 optionally limits to runs linked to these dataset example UUIDs.

run_type, when set, restricts results to runs whose run_type equals this value.

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 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 optionally limits results to runs belonging to this trace UUID.

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.

Chat LangChain

What can I help with?

Menu

Parameters