Trace query syntax

Using the list_runs method in the SDK or /runs/query endpoint in the API, you can filter runs to analyze and export.

Filter arguments

Keys	Description
project_id / project_name	The project(s) to fetch runs from - can be 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, such as llm, chain, tool, retriever, etc.
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. See the guide below for more information.
trace_filter	Filter to apply to the ROOT run in the trace tree. This is meant to be used in conjunction with the regular filter parameter to let you filter runs by attributes of the root run within a trace.
tree_filter	Filter to apply to OTHER runs in the trace tree, including sibling and child runs. This is meant to be used in conjunction with the regular filter parameter to let you filter runs 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.
query (experimental)	Natural language query, which translates your query into a filter statement.

Filter query language

LangSmith supports powerful filtering capabilities with a filter query language to permit complex filtering operations when fetching runs.

The filtering grammar is based on common comparators on fields in the run object. Supported comparators include:

• gte (greater than or equal to)
• gt (greater than)
• lte (less than or equal to)
• lt (less than)
• eq (equal to)
• neq (not equal to)
• has (check if run contains a tag or metadata json blob)
• search (search for a substring in a string field)

Additionally, you can combine multiple comparisons through and and or operators.

These can be applied on fields of the run object, such as its id, name, run_type, start_time / end_time, latency, total_tokens, error, execution_order, tags, and any associated feedback through feedback_key and feedback_score.