> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-docsby-1791319236-3be7a15.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Trace query syntax

The [LangSmith SDK](https://reference.langchain.com/python/langsmith/) and [REST API](/langsmith/smith-api-ref) let you filter, query, and export [runs](/langsmith/observability-concepts#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](/langsmith/export-traces).

## 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](/langsmith/run-data-format#run-types) 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](#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](/langsmith/run-data-format) for available fields. |
| `query` (*experimental*) | Natural language query, which translates your query into a filter statement. |

<Note>
  **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.
</Note>

## 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](/langsmith/evaluation) pipelines, monitoring scripts, or agentic workflows that inspect prior [traces](/langsmith/observability-concepts#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:

```text theme={null}
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.

<Tip>
  For complete SDK examples with Python, TypeScript, and Java code, refer to [Query traces using the SDK](/langsmith/export-traces#use-filter-query-language).
</Tip>

### Filter by run name

```text theme={null}
eq(name, "my_chain")
```

### Filter by error status

```text theme={null}
# Runs that errored
eq(status, "error")

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

### Filter by latency

```text theme={null}
# Runs slower than 5 seconds
gt(latency, "5s")

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

### Filter by time range

```text theme={null}
and(gt(start_time, "2024-01-01T00:00:00Z"), lt(start_time, "2024-02-01T00:00:00Z"))
```

### Filter by tags

```text theme={null}
has(tags, "production")

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

### Filter by metadata key or value

```text theme={null}
# 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

```text theme={null}
and(in(metadata_key, ["session_id", "thread_id"]), eq(metadata_value, "<your_thread_id>"))
```

### Filter by feedback score

```text theme={null}
# 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

```text theme={null}
search("my search term")
```

### Combining conditions

```text theme={null}
# 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.

```text theme={null}
# 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")
```

<Note>
  `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](/langsmith/export-traces#query-trace-trees-with-child-run-predicates).
</Note>

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to your agent of choice via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/trace-query-syntax.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>