Trace query syntax

The LangSmith SDK and REST API let you filter, query, and export runs programmatically using a set of filter arguments and a structured filter query language. This page documents the filter arguments and query language, with examples for common queries.

For runnable end-to-end examples that combine these filters with the SDK, refer to Query traces using the SDK.

Filter arguments

Keys	Description
project_id / project_name	The project(s) to fetch runs from, as a single project or a list of projects.
trace_id	Fetch runs that are part of a specific trace.
run_type	The type of run to get, for example, llm, chain, tool, retriever.
dataset_name / dataset_id	Fetch runs that are associated with an example row in the specified dataset. This is useful for comparing prompts or models over a given dataset.
reference_example_id	Fetch runs that are associated with a specific example row. This is useful for comparing prompts or models on a given input.
parent_run_id	Fetch runs that are children of a given run. This is useful for fetching runs grouped together using the context manager or for fetching an agent trajectory.
error	Fetch runs that errored or did not error.
run_ids	Fetch runs with a given list of run ids. Note: This will ignore all other filtering arguments.
filter	Fetch runs that match a given structured filter statement. For more details, refer to the filter query language section.
trace_filter	Filter applied to the root run of the trace. Use with filter to narrow by attributes of the root run.
tree_filter	Filter applied to any run in the trace tree (root, sibling, or child). Use with filter to narrow by attributes of any run within a trace.
is_root	Only return root runs.
select	Select the fields to return in the response. By default, all fields are returned. See run data format for available fields.
query (experimental)	Natural language query, which translates your query into a filter statement.

Performance tip: Passing the select parameter and excluding inputs and outputs from the list can significantly improve query performance and reduce response sizes, especially for large runs.

Filter query language

LangSmith supports filtering capabilities with a filter query language to permit complex filtering operations when fetching runs. This is especially useful when querying traces programmatically via the SDK or API. For example, in evaluation pipelines, monitoring scripts, or agentic workflows that inspect prior traces.

Comparators

The filtering grammar is based on comparator functions applied to fields of the run object:

Comparator	Description	Example
eq	Equal to	eq(run_type, "llm")
neq	Not equal to	neq(status, "error")
gt	Greater than	gt(latency, "5s")
gte	Greater than or equal to	gte(latency, 1.5)
lt	Less than	lt(start_time, "2024-01-01T00:00:00Z")
lte	Less than or equal to	lte(feedback_score, 0.5)
has	Check if the run contains a tag or metadata key-value	has(tags, "production")
search	Search for a substring across all string fields	search("invoice")
in	Check if a field value is in a list	in(metadata_key, ["session_id", "thread_id"])

Logical operators

Use and and or to combine multiple comparators:

and(eq(run_type, "llm"), gt(latency, "2s"))
or(eq(status, "error"), and(eq(feedback_key, "score"), lt(feedback_score, 0.5)))

Filterable fields

Field	Type	Notes
id	string (UUID)	Run ID
name	string	Name of the run
run_type	string	One of llm, chain, tool, retriever, embedding, prompt, parser
status	string	"success", "error", or "pending". Use this to filter errored vs. successful runs.
start_time	ISO 8601 string	e.g. "2024-01-15T00:00:00Z"
end_time	ISO 8601 string
latency	duration string or number	Seconds, e.g. "5s", "1.5s", or 1.5. Only the s suffix is supported.
tags	list of strings	Use has(tags, "value")
metadata_key	string	Key in the run’s metadata dict
metadata_value	string	Value in the run’s metadata dict
feedback_key	string	Name of a feedback score
feedback_score	number	Numeric value of a feedback score

Value formatting

• Strings: wrap in double or single quotes, eq(name, "MyChain") or eq(name, 'MyChain').
• Timestamps: ISO 8601 format, "2024-06-01T00:00:00Z".
• Durations: seconds, as either a number or a string with the s suffix, "5s", "1.5s", "90s", or 1.5. Other unit suffixes (m, h) are not supported.
• Lists: JSON array syntax, ["session_id", "thread_id"].

Quick reference examples

The following examples show the filter string only. Pass the string as the filter, trace_filter, or tree_filter argument in client.list_runs() or the /runs/query API endpoint.

For complete SDK examples with Python, TypeScript, and Java code, refer to Query traces using the SDK.

Filter by run name

eq(name, "my_chain")

Filter by error status

# Runs that errored
eq(status, "error")

# Runs that did not error
eq(status, "success")

Filter by latency

# Runs slower than 5 seconds
gt(latency, "5s")

# Runs faster than 1 second
lt(latency, "1s")

Filter by time range

and(gt(start_time, "2024-01-01T00:00:00Z"), lt(start_time, "2024-02-01T00:00:00Z"))

Filter by tags

has(tags, "production")

# Multiple tags (any match)
or(has(tags, "production"), has(tags, "staging"))

Filter by metadata key or value

# Runs with a "user_id" metadata key
eq(metadata_key, "user_id")

# Runs with a specific user ID value
and(eq(metadata_key, "user_id"), eq(metadata_value, "usr_abc123"))

# Runs from the production environment
and(eq(metadata_key, "environment"), eq(metadata_value, "production"))

Filter by thread ID

and(in(metadata_key, ["session_id", "thread_id"]), eq(metadata_value, "<your_thread_id>"))

Filter by feedback score

# Runs with a "thumbs_up" score of 1
and(eq(feedback_key, "thumbs_up"), eq(feedback_score, 1))

# Runs with a "correctness" score below 0.5
and(eq(feedback_key, "correctness"), lt(feedback_score, 0.5))

Full-text search across all string fields

search("my search term")

Combining conditions

# Errors that started after a specific time
and(gt(start_time, "2024-06-01T00:00:00Z"), eq(status, "error"))

# Slow LLM runs with low correctness feedback
and(gt(latency, "10s"), eq(feedback_key, "correctness"), lt(feedback_score, 0.5))

# Complex: errors OR low score, both starting after a timestamp
and(gt(start_time, "2023-07-15T12:34:56Z"), or(eq(status, "error"), and(eq(feedback_key, "Correctness"), eq(feedback_score, 0.0))))

Using trace_filter and tree_filter

filter applies to the returned run. trace_filter applies to the root run of the trace. tree_filter applies to any run anywhere in the trace tree.

# filter: the run you want
eq(name, "RetrieveDocs")

# trace_filter: condition on the root run (e.g. human feedback on the overall trace)
and(eq(feedback_key, "user_score"), eq(feedback_score, 1))

# tree_filter: condition on any run in the trace tree
eq(name, "ExpandQuery")

tree_filter applies the same query syntax to runs anywhere in the trace tree. For predicates over arbitrary nested child-run fields, such as returned inputs, outputs, or extra payload paths, first narrow candidates with server-side filters, then hydrate root traces with child runs and traverse them locally. See Query trace trees with child-run predicates.

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.