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

# Filter traces

> Filter threads, traces, and runs in a LangSmith tracing project using the search bar query syntax, filter scopes, shortcuts, and saved views.

Tracing projects accumulate large amounts of data across [threads](/langsmith/observability-concepts#threads), [traces](/langsmith/observability-concepts#traces), and [runs](/langsmith/observability-concepts#runs). The search bar at the top of a tracing project narrows that data down: write one or more `field:value` clauses, combine them with `AND` and `OR`, and choose which runs in the trace hierarchy each clause applies to.

<Note>
  Tracing projects have two filtering experiences. Check the top of your project to see which one applies to you:

  * **A single search bar with a scope selector to its left**: Refer to [Filter traces](/langsmith/filter-traces).
  * **An Add filter button that builds filter chips**: Refer to [Filter traces in application](/langsmith/filter-traces-in-application).
</Note>

This page covers:

* [Building a query](#build-a-query) in the search bar
* [Query syntax](#query-syntax) and the [fields](#fields) available to filter on
* [What full-text search indexes](#full-text-search-indexing)
* [Choosing what a filter matches](#choose-what-a-filter-matches) with scopes
* [Filtering in one click](#filter-with-shortcuts) from the **Shortcuts** panel
* [Saving a filter](#save-a-filter) as a view
* [Filtering the runs inside a trace](#filter-the-runs-in-a-trace)

To query runs programmatically instead, refer to [Query traces using the SDK](/langsmith/export-traces). The SDK and REST API use a separate structured query language, documented in [Trace query syntax](/langsmith/trace-query-syntax).

## Build a query

Click the search bar and start typing to open the query builder:

<Steps>
  <Step title="Choose a field">
    Type a field name or select one from the suggestion list. Suggestions are grouped by category, and **Recents** lists queries run previously. Use the arrow keys to move through the list and press `Enter` to select.
  </Step>

  <Step title="Choose an operator">
    Type `:` to see the operators the field supports, each with an example.
  </Step>

  <Step title="Enter a value">
    For fields whose values LangSmith indexes, such as run names and tags, the suggestion list offers the most common values in the project.
  </Step>
</Steps>

Each completed clause becomes a chip in the bar. Click a chip to edit it, or click its remove icon to delete it. Keep typing after a chip to add another clause.

The time range control above the table applies independently of the query, as does the **Threads**, **Traces**, and **Runs** selection. Refer to [Choose what a filter matches](#choose-what-a-filter-matches).

<Note>
  The search bar uses the syntax described on this page, which is not the structured query language that the SDK and REST API accept. Refer to [Trace query syntax](/langsmith/trace-query-syntax) for that language.
</Note>

## Query syntax

A clause pairs a field with an operator and a value:

```text theme={null}
status:error
```

### Operators

The operators a field accepts depend on its type.

| Operator                 | Syntax             | Matches                                                                                            |
| ------------------------ | ------------------ | -------------------------------------------------------------------------------------------------- |
| is                       | `field:value`      | An exact match on the value.                                                                       |
| is not                   | `-field:value`     | Everything except an exact match.                                                                  |
| matches                  | `field:~value`     | A full-text search of the field. Quote the value to search for a phrase.                           |
| does not match           | `-field:~value`    | Everything the full-text search does not match.                                                    |
| wildcard                 | `field:value*`     | A pattern, where `*` stands for any sequence of characters.                                        |
| exists                   | `field:*`          | Records where the field is set.                                                                    |
| does not exist           | `-field:*`         | Records where the field is not set.                                                                |
| greater than             | `field:>value`     | Values above the given value.                                                                      |
| greater than or equal to | `field:>=value`    | Values at or above the given value.                                                                |
| less than                | `field:<value`     | Values below the given value.                                                                      |
| less than or equal to    | `field:<=value`    | Values at or below the given value.                                                                |
| inclusive range          | `field:[10 TO 20]` | Values from 10 to 20, including both bounds.                                                       |
| exclusive range          | `field:{10 TO 20}` | Values between 10 and 20, excluding both bounds.                                                   |
| mixed range              | `field:[10 TO 20}` | Values from 10 up to but not including 20. Swap the delimiters to invert which bound is inclusive. |

Some fields accept only a subset of these operators:

* **Full-text fields**: `input`, `output`, `metadata`, and `error` accept `~` only.
* **Comparison and range operators**: These apply to numeric and timestamp fields, and to numeric [`metadata` paths](#match-a-json-key).

<Note>
  To match any of several values, combine clauses with `OR`, for example `status:error OR status:interrupted`. Listing several values inside one clause is not supported.
</Note>

### Combine clauses

Combine clauses with `AND`, `OR`, `NOT`, and parentheses:

* **`AND`**: Both clauses must match. Whitespace between two clauses acts as `AND`, so `status:error run_type:llm` and `status:error AND run_type:llm` are equivalent.
* **`OR`**: Either clause must match.
* **`NOT`**: Negates the clause that follows. The `-` prefix does the same thing, so `NOT status:error` and `-status:error` are equivalent.
* **Parentheses**: Group clauses to control precedence.

`AND` binds more tightly than `OR`, so `a OR b AND c` matches `a OR (b AND c)`. Group clauses to change that: `(a OR b) AND c`.

Keywords are case-insensitive.

### Quote values

Double-quote a value that contains a space, contains a colon, or includes a character to match literally:

```text theme={null}
name:"docs agent"
tags:"env:prod"
```

Quoting also turns off wildcard matching, so `name:"docs*"` matches the literal string `docs*`. As an alternative to quoting, escape the character with a backslash, as in `name:docs\ agent`.

An unquoted value containing a space splits into two clauses. `name:docs agent` matches runs whose name is `docs` and whose indexed content contains `agent`.

### Search without naming a field

In the **Single run**, **Root run**, and **Any run** [scopes](#choose-what-a-filter-matches), a bare term searches every indexed field:

```text theme={null}
"capital of France"
```

The **Thread** scope does not support bare-term search.

## Fields

The suggestion list groups fields into categories. The available fields depend on the [scope](#choose-what-a-filter-matches) of the filter row.

### Run fields

These fields are available in the **Single run**, **Root run**, and **Any run** scopes.

**Run attributes**

| Field      | Description                                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------ |
| `name`     | Run name. Supports `*` wildcards.                                                                            |
| `status`   | Run status: `pending`, `success`, `error`, or `interrupted`.                                                 |
| `run_type` | The [type of run](/langsmith/run-data-format#run-types), for example `llm`, `chain`, `tool`, or `retriever`. |
| `tags`     | Run tags. A clause matches if any tag on the run matches.                                                    |

**Content**

| Field         | Description                                                                               |
| ------------- | ----------------------------------------------------------------------------------------- |
| `input`       | Run inputs. Use `~` to search the text, or `input.<key>` to match a JSON key.             |
| `output`      | Run outputs. Use `~` to search the text, or `output.<key>` to match a JSON key.           |
| `metadata`    | Run metadata. Use `metadata.<key>` to match a JSON key, or `~` to search metadata values. |
| `error`       | Error text. Use `~` to search the text.                                                   |
| `attachments` | Attachment names. Accepts the is, is not, wildcard, and exists operators.                 |

**Identity**

| Field           | Description     |
| --------------- | --------------- |
| `id`            | Run ID.         |
| `trace_id`      | Trace ID.       |
| `thread_id`     | Thread ID.      |
| `parent_run_id` | Parent run ID.  |
| `ls_user_id`    | LangSmith user. |

**Performance**

| Field                                                | Description                                                                                                                                     |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `latency`                                            | Run duration in seconds.                                                                                                                        |
| `first_token_time`                                   | When the first token was produced.                                                                                                              |
| `prompt_tokens`, `completion_tokens`, `total_tokens` | Token counts for the run.                                                                                                                       |
| `prompt_cost`, `completion_cost`, `total_cost`       | Costs for the run.                                                                                                                              |
| `prompt_token_details`, `completion_token_details`   | Token breakdowns. Address a component with dot notation, for example `prompt_token_details.cache_read` or `completion_token_details.reasoning`. |
| `prompt_cost_details`, `completion_cost_details`     | Cost breakdowns, with the same components as the token breakdowns.                                                                              |

**Feedback**

| Field      | Description                                                              |
| ---------- | ------------------------------------------------------------------------ |
| `feedback` | Feedback on the run. Refer to [Filter on feedback](#filter-on-feedback). |

Run metadata and tags are often the most useful fields to filter on, and they depend on consistent tagging across your application. To learn more, refer to [Add metadata and tags to traces](/langsmith/add-metadata-tags).

### Thread fields

The **Thread** scope filters on attributes of the thread as a whole, so it supports a different set of fields. The suggestion list labels the group **Thread attributes**.

| Field                                                                                                | Description                                  |
| ---------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `thread_id`                                                                                          | Thread ID.                                   |
| `turn_count`                                                                                         | Turns in the thread.                         |
| `num_errored_turns`                                                                                  | Turns that ended in an error.                |
| `thread_duration`                                                                                    | First turn start to last turn end.           |
| `trace_latency_p50`                                                                                  | Median turn latency.                         |
| `trace_latency_p99`                                                                                  | P99 turn latency.                            |
| `total_tokens`                                                                                       | Tokens across the thread.                    |
| `total_cost`                                                                                         | Cost across the thread.                      |
| `prompt_token_details`, `completion_token_details`, `prompt_cost_details`, `completion_cost_details` | Token and cost breakdowns across the thread. |

<Note>
  Run fields such as `name`, `status`, and `input` are not available in the **Thread** scope. To filter threads by an attribute of the runs they contain, add a second filter row in the **Any run** scope. Refer to [Combine scopes](#combine-scopes).
</Note>

### Match a JSON key

`input`, `output`, and `metadata` hold JSON. Address a key inside them with dot notation:

```text theme={null}
metadata.env:production
input.user_id:abc123
output.status:success
```

Nested paths work the same way, for example `metadata.config.temperature:0.7`. Quote a key that contains a dot, as in `metadata."my.key":production`.

Only `metadata` paths support comparison and range operators, and only where the values are numeric:

```text theme={null}
metadata.retries:>=3
```

### Filter on feedback

Address a feedback key and one of its subfields with dot notation:

```text theme={null}
feedback.correctness.score:>=0.5
feedback.relevance.value:pass
feedback.quality.comment:~helpful
```

The available subfields are `key`, `score`, `source`, `value`, `error`, and `comment`. In the **Thread** scope, only `key`, `score`, and `value` are available.

To match records that carry any feedback at all, use `feedback:*`. To match records that carry a particular feedback key regardless of its value, use `feedback.<key>:*`. Comparing a value requires naming a subfield, so `feedback.correctness:0.5` is not valid.

Wrap several feedback conditions in `feedback:{…}` to group them:

```text theme={null}
feedback:{correctness.score:>0.5}
```

## Full-text search indexing

The `~` operator and [bare-term searches](#search-without-naming-a-field) match against a derived search index rather than against the stored run data. LangSmith builds that index by extracting search tokens recursively from the string values in run inputs, outputs, and errors. Object keys are not indexed, and a value is neither rejected nor truncated because of its length. Metadata is indexed separately, for structured key and path filtering, and is not subject to the limits below.

The following limits apply to the index:

* **Tokens per field**: LangSmith retains up to 2,000 distinct search tokens for each indexed field, selected from up to 200,000 distinct candidates.
* **Nesting depth**: LangSmith processes nested data to a maximum depth of 30.
* **Token length**: A search token runs between 2 and 44 characters for typical ASCII text. Strings outside that range are not indexed.
* **Excluded content**: URLs, image data URLs, common stopwords, and numeric-only tokens are not indexed.

These limits govern the search index only. They place no limit on the run data LangSmith stores, so a value the index leaves out is still visible in the trace itself.

Key-path filtering is separate from full-text search and is not subject to the full-text token limits. LangSmith does not currently publish separate limits for key-path filtering. A filter such as `input.<key>` or `metadata.<key>` looks for a value at a specific path, so it can still match values the full-text index omits. Refer to [Match a JSON key](#match-a-json-key).

## Choose what a filter matches

The **Threads**, **Traces**, and **Runs** selection above the table controls what each row represents. The scope selector, to the left of the search bar, separately controls which runs a clause is tested against. Together they replace the trace and tree filters of the previous filtering experience.

Four scopes are available:

* **Thread**: Matches the entire thread.
* **Root run**: Matches only the entry runs.
* **Single run**: Matches the run itself.
* **Any run**: Matches anywhere in the tree.

Each option in the scope dropdown includes a preview illustrating which runs it covers.

The scopes offered, and the one selected by default, depend on the table selection:

| Table selection | Default scope | Available scopes              |
| --------------- | ------------- | ----------------------------- |
| **Threads**     | Any run       | Thread, Root run, Any run     |
| **Traces**      | Any run       | Root run, Any run             |
| **Runs**        | Single run    | Single run, Root run, Any run |

### Combine scopes

To filter on more than one scope at a time, click **Filter**. This adds a row with its own scope selector and search bar. Rows combine with `AND`, so a thread, trace, or run must satisfy every row to appear in the table.

Each scope holds one row, so a table selection accepts as many rows as it has scopes. **Filter** is disabled once every available scope is in use. To remove a row, click **Remove filter** next to it.

For example, in the **Threads** view, find threads longer than 20 turns that contain a failed tool call:

| Scope   | Query                            |
| ------- | -------------------------------- |
| Thread  | `turn_count:>20`                 |
| Any run | `run_type:tool AND status:error` |

### Scopes a table selection cannot use

Changing the table selection can leave a row on a scope the new selection does not support, such as a **Single run** row after switching from **Runs** to **Threads**. The row stays visible with a **Not applied** badge, and its query is preserved but not sent. Change the row's scope or return to a compatible table selection to apply it again.

## Filter with shortcuts

The **Shortcuts** panel to the left of the table lists the most common values in the project, grouped by **Status**, **Run Name**, **Run Type**, **Tag**, **Metadata**, and **Feedback**. Selecting a value adds the matching clause to the search bar, which makes the most common filters a one-click operation.

Each group header shows how many of its values are active. Use the search box in the **Feedback** group to find a feedback key.

To give the table more room, click **Hide shortcuts**, then **Show shortcuts** to bring the panel back. The **Stats** panel on the right collapses the same way, with **Hide stats** and **Show stats**.

## Save a filter

Saved views store a filter for reuse. Views are specific to a tracing project.

To save the current filter:

1. Build the query.
2. Click **Save View**.
3. Enter a name and description, then save.

The view then appears in the **Views** dropdown alongside **Default view**. Each entry lists the scopes its filter uses, which shows at a glance whether it applies to the current table selection.

To update a saved view, select it, change the query, then click **Save View**. To rename or delete a view, click the <Icon icon="dots-vertical" /> icon next to it in the **Views** dropdown.

To discard unsaved changes and return to the selected view, click **Reset**.

### Views saved with the previous syntax

Views saved before this filtering experience shipped continue to work. Selecting one translates its filters into the syntax on this page, and LangSmith prompts you to save the translated view.

## Filter the runs in a trace

When a trace contains many runs, filter the run list to locate the ones you care about instead of reading through the whole tree. Open a thread or trace to reach the [Details view](/langsmith/view-traces#details-view), then use **Filter runs** above the run list.

This search bar accepts the same fields and syntax as the **Single run** scope on the project page. It has no scope selector, because it always matches individual runs within the open trace. To remove the filter, click **Clear run filter**.

Runs that match are highlighted in the run list, and the rest of the trace stays visible around them. A filter applied in the **Any run** scope carries over automatically, so opening a thread or trace from the table highlights the runs that matched.

The **Visibility** options behind the <Icon icon="settings" /> icon above the run list, **Most relevant** and **Show All**, are disabled while a filter is applied.

## See also

* [View traces](/langsmith/view-traces)
* [Threads](/langsmith/threads)
* [Add metadata and tags to traces](/langsmith/add-metadata-tags)
* [Trace query syntax](/langsmith/trace-query-syntax) for the SDK and REST API query language
* [Query traces using the SDK](/langsmith/export-traces)

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more 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/filter-traces.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>