Filter traces

Filtering is how you get from every run in a tracing project to the few you need: the conversations that errored, the tool calls that ran slowly, the runs a low feedback score points at. Write a query in the search bar, and choose which runs in the trace or thread hierarchy that query is tested against.

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
Choosing what a filter matches with scopes
Query syntax and the fields available to filter on
Examples to copy and adapt
Filtering in one click from the Shortcuts panel
Saving a filter as a view
Filtering the runs inside a trace
What full-text search indexes
Troubleshooting a query

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

A query is made of clauses, and each clause pairs a field with an operator and a value:

status:error

Click the search bar and start typing to build one:

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. Two controls outside the search bar also affect the results:

The time range control applies alongside the query. Results must fall inside the time range and match the query.
The Threads, Traces, and Runs selection sets what each row in the table represents, and it also determines which scopes a query can use.

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.

Choose what a filter matches

A trace is a tree of runs, and a thread is a series of traces. A clause such as status:error is ambiguous until you say which runs in that hierarchy it applies to: the run that started the trace, any run anywhere inside it, or the thread as a whole. The scope selector, to the left of the search bar, is where you say so. 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.

The scope dropdown previews each option against a sample trace, so you can see which runs it covers before choosing: 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 at most one row, so the Threads and Runs selections accept three rows and Traces accepts two. 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 applied. Change the row’s scope or return to a compatible table selection to apply it again.

Query syntax

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.
comparison	`field:>value`	Values above the given value. Also accepts `>=`, `<`, and `<=`.
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.

* means two different things depending on where it appears. On its own after the colon it tests for existence, so name:* matches every run that has a name. Inside a value it is a wildcard, so name:docs* matches names beginning with docs.

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 fields such as latency and total_tokens, to timestamp fields such as first_token_time, 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. In the run scopes, an unquoted value containing a space splits into two clauses, so 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.

Identity

Field	Description
`id`, `trace_id`, `thread_id`, `parent_run_id`	Match a specific run, trace, thread, or parent run by its ID.
`ls_user_id`	The LangSmith user the run is attributed to.

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.

Metadata and tags are usually the most productive fields to filter on, because you control what goes in them. See 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, value, comment, source, and error. 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. Group a feedback condition with feedback:{...}:

feedback:{correctness.score:>0.5}

Examples

Queries to copy and adapt. Each assumes the default scope for its table selection. Errored LLM calls that were also slow. Use the Runs selection:

run_type:llm AND status:error AND latency:>10

Runs your evaluator scored poorly. Use the Runs selection:

run_type:llm AND feedback.correctness.score:<0.5

Production traffic that did not succeed. Use the Traces selection:

metadata.env:production AND -status:success

Conversations that mention a topic and went wrong. Use the Threads selection:

input:~"refund" AND status:error

Traces that called a specific tool. Use the Traces selection:

run_type:tool AND name:search_documents

Expensive traces. Use the Traces selection with the Root run scope:

total_cost:>0.5

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. These groups correspond to the status, name, run_type, tags, metadata, and feedback fields. Selecting a value adds the matching clause to the search bar, so the most common filters take one click instead of a typed query. 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. A view belongs to the tracing project rather than to the person who created it, so anyone with access to the project can select it. 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

Filtering inside an open trace highlights the runs that match, which is how you find the one that matters in a large trace. Open a thread or trace to reach the Details view, then use Filter runs above the run list. Matching runs are highlighted in place, and the rest of the trace stays visible around them, so a match keeps the context that explains it. 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 it. 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 the clear icon in the filter box. The Visibility options behind the icon above the run list, Most relevant and Show All, are disabled while a filter is applied.

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. 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 of ASCII text. Strings outside that range are not indexed, and non-ASCII text is measured by the space it occupies rather than by character count.
Excluded content: URLs, image data URLs, numeric-only tokens, and common stopwords such as “the” and “of” are not indexed.

These limits govern the search index only. Run data is stored in full, so a value the index leaves out is still visible in the trace itself. Metadata and key paths are indexed separately. Key-path filtering is not subject to the full-text token limits, and LangSmith does not currently publish separate limits for it. 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.

Troubleshoot a query

The search bar flags the query as invalid. The bar validates as you type and names the problem inline, including unknown field names, unbalanced quotes or brackets, and an operator separated from its colon by a space. Fix the clause it points at. The query is valid but matches nothing. Work through these in order:

Check the time range. It applies alongside the query, so a correct filter still returns nothing if the matching runs fall outside the window.
Check the scope. A clause tested against the wrong level of the hierarchy is the most common cause. Filtering traces on run_type:llm in the Root run scope matches only traces whose entry run is an LLM call, which is rarely what you want. Switch that row to Any run.
Check for a Not applied badge. A row on a scope the current table selection does not support is preserved but not applied.
Check whether the value is indexed. Full-text search skips URLs, stopwords, numeric-only tokens, and very short or very long tokens. Filter on a JSON key instead, which is not subject to those limits.

Viewing & managing traces

Bulk export trace data

Messages view

Data type reference

Build a query

Choose what a filter matches

Combine scopes

Scopes a table selection cannot use

Query syntax

Operators

Combine clauses

Quote values

Search without naming a field

Fields

Run fields

Thread fields

Match a JSON key

Filter on feedback

Examples

Filter with shortcuts

Save a filter

Views saved with the previous syntax

Filter the runs in a trace

Full-text search indexing

Troubleshoot a query

See also

​Build a query

​Choose what a filter matches

​Combine scopes

​Scopes a table selection cannot use

​Query syntax

​Operators

​Combine clauses

​Quote values

​Search without naming a field

​Fields

​Run fields

​Thread fields

​Match a JSON key

​Filter on feedback

​Examples

​Filter with shortcuts

​Save a filter

​Views saved with the previous syntax

​Filter the runs in a trace

​Full-text search indexing

​Troubleshoot a query

​See also

Build a query

Choose what a filter matches

Combine scopes

Scopes a table selection cannot use

Query syntax

Operators

Combine clauses

Quote values

Search without naming a field

Fields

Run fields

Thread fields

Match a JSON key

Filter on feedback

Examples

Filter with shortcuts

Save a filter

Views saved with the previous syntax

Filter the runs in a trace

Full-text search indexing

Troubleshoot a query

See also