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 |
- 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", "conversation_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.
Filter by run name
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"))
has(tags, "production")
# Multiple tags (any match)
or(has(tags, "production"), has(tags, "staging"))
# 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 conversation or thread ID
and(in(metadata_key, ["session_id", "conversation_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
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.
Engine