Filter traces

Tracing projects accumulate large amounts of data across threads, traces, and 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.

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.
An Add filter button that builds filter chips: Refer to Filter traces in application.

This page covers:

Building a query in the search bar
Query syntax and the fields available to filter on
What full-text search indexes
Choosing what a filter matches with scopes
Filtering in one click from the Shortcuts panel
Saving a filter as a view
Filtering the runs inside a trace

To query runs programmatically instead, refer to Query traces using the SDK. The SDK and REST API use a separate structured query language, documented in Trace query syntax.

Build a query

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

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.

Choose an operator

Type : to see the operators the field supports, each with an example.

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.

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.

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 for that language.

Query syntax

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

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.

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.

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:

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, a bare term searches every indexed field:

"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 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, 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.

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.

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.

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.

Match a JSON key

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

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:

metadata.retries:>=3

Filter on feedback

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

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:

feedback:{correctness.score:>0.5}

Full-text search indexing

The ~ operator and bare-term searches 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.

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:

Build the query.
Click Save View.
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 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, 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 above the run list, Most relevant and Show All, are disabled while a filter is applied.

Viewing & managing traces

Bulk export trace data

Messages view

Data type reference

Build a query

Query syntax

Operators

Combine clauses

Quote values

Search without naming a field

Fields

Run fields

Thread fields

Match a JSON key

Filter on feedback

Full-text search indexing

Choose what a filter matches

Combine scopes

Scopes a table selection cannot use

Filter with shortcuts

Save a filter

Views saved with the previous syntax

Filter the runs in a trace

See also

​Build a query

​Query syntax

​Operators

​Combine clauses

​Quote values

​Search without naming a field

​Fields

​Run fields

​Thread fields

​Match a JSON key

​Filter on feedback

​Full-text search indexing

​Choose what a filter matches

​Combine scopes

​Scopes a table selection cannot use

​Filter with shortcuts

​Save a filter

​Views saved with the previous syntax

​Filter the runs in a trace

​See also

Build a query

Query syntax

Operators

Combine clauses

Quote values

Search without naming a field

Fields

Run fields

Thread fields

Match a JSON key

Filter on feedback

Full-text search indexing

Choose what a filter matches

Combine scopes

Scopes a table selection cannot use

Filter with shortcuts

Save a filter

Views saved with the previous syntax

Filter the runs in a trace

See also