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 (ClickHouse).
- 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
- Searching with AI in natural language instead of field values (beta)
- What full-text search indexes
- Troubleshooting a query
Build a query
A query is made of clauses, and each clause pairs a field with an operator and a value:

1
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.If AI search is available to your organization, AI search appears at the top of the suggestion list. Refer to Search with AI.2
Choose an operator
Type
: to see the operators the field supports, each with an example.3
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.
- 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 asstatus: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.


To describe what you want in plain language instead of writing query syntax, use AI search.
Combine scopes
To filter on more than one scope at a time, click the Add filter scope icon at the end of the last row. This adds a row with its own scope selector and search bar, labeled AND. Rows combine withAND, 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 filter rows and Traces accepts two. Add filter scope 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:


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.
Some fields accept only a subset of these operators:
- Full-text fields:
input,output,metadata, anderroraccept~only. - Comparison and range operators: These apply to numeric fields such as
latencyandtotal_tokens, to timestamp fields such asfirst_token_time, and to numericmetadatapaths.
OR, for example status:error OR status:interrupted. Listing several values inside one clause is not supported.
Combine clauses
Combine clauses withAND, OR, NOT, and parentheses:
AND: Both clauses must match. Whitespace between two clauses acts asAND, sostatus:error run_type:llmandstatus:error AND run_type:llmare equivalent.OR: Either clause must match.NOT: Negates the clause that follows. The-prefix does the same thing, soNOT status:errorand-status:errorare 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*" 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: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
Content
Identity
Performance
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.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.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:
Filter on feedback
Address a feedback key and one of its subfields with dot notation: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:{...}:
Examples
Queries to copy and adapt. Each assumes the default scope for its table selection unless stated otherwise. Errored LLM calls that were also slow. Use the Runs selection: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 thestatus, 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.


Save a filter
Saved views store a filter for reuse. A view belongs to one environment rather than to the person who created it, so anyone with access to the environment can select it. A view saved in Production is not offered in Staging, and a filter you want in every environment has to be saved in each. To save the current filter:- Build the query.
- Click Save View.
- Enter a name and description, then save.
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.

Search with AI
AI search turns a plain-language description into a search. Describe what you want, and LangSmith works out the filters, the table selection, the time range, and any conditions about what happens in the conversation. For example:threads with more than 5 turns where the user got confusedllm calls that errored in the last 2 daysthreads where agent didn't complete the task and spent more than $1
AI search is in beta and available on all LangSmith Cloud SaaS instances. It works in the Threads, Traces, and Runs selections once an organization admin enables it. Refer to Enable AI search.
-
Open AI search in one of these ways:
- Click the AI search icon in the first filter row.
- Select AI search at the top of the search bar’s suggestion list. Any text you have typed carries over as the start of the description.
- Describe what you are looking for. While the field is empty, a tip below it offers examples. Selecting an example fills the field without searching, so you can edit it first.
-
Press
Enter, or click the Search button.
- Filters: Structured conditions become filters in the matching scopes. Conditions about the meaning of the conversation, such as
the user got confused, become an AI condition matched against each trajectory. - Table selection: LangSmith switches to the Threads, Traces, or Runs selection that fits the description.
- Time range: A time period in the description, such as
in the last 2 days, updates the time range control.
Edit the applied filters
To adjust what LangSmith applied, click Exit AI search on the AI search chip. The search bar returns to filter rows holding the applied filters, which you can edit directly. An AI condition stays as a read-only row. To go back to AI search, open it again; if you have not changed the filters, LangSmith restores your last description. Results must match every applied filter, the AI condition, and the time range. The description can be up to 2,000 bytes.Search with AI using the SDK
The SDK streaming query methods acceptai_search for runs, traces, and threads. LangSmith interprets the description the same way as the UI: structured conditions become filters, a time period in the description sets the time bounds, and conditions about the conversation are matched against each trajectory. The method you call sets the scope. AI search in the SDK has the same organization opt-in and data-handling requirements as the UI.
The following examples require
langsmith>=0.14.14 for Python or langsmith>=0.11.3 for TypeScript.- Python
- TypeScript
- Runs:
client.runs.streaming.query_v2_items(project_ids=["<project-id>"], ai_search="llm calls that errored in the last 2 days") - Traces:
client.traces.streaming.query_items(project_id="<project-id>", ai_search="traces where the user got confused")
AsyncLangsmith, use async for with the same methods.ai_search:
- The description must be nonempty and at most 2,000 UTF-8 bytes.
- Do not also pass
filter,trace_filter,tree_filter, orthread_filter. LangSmith builds those from the description, and a request that sets both returns HTTP400. Other parameters, such as selected fields and page size, apply as usual. - A time period in the description replaces
min_start_timeandmax_start_time. Bounds the description does not mention keep the values you pass, or the method’s defaults.
query_v2_items / queryV2Items and query_items / queryItems methods follow pagination cursors and return assembled runs, traces, or threads. The lower-level query_v2 / queryV2 and query methods return server-sent events containing JSON patches instead.
AI search requires Accept: text/event-stream, which the streaming methods set automatically. Passing ai_search to a non-streaming query returns HTTP 406. Deployments that route queries to the legacy v1 backend return HTTP 501.
For terminal usage, see Search with AI using the CLI.
Review why a result matched
When you open a thread, trace, or run from AI search results, LangSmith opens it in the Trajectory view at the messages that matched the description, so you can see why it matched. A thread opens at the first trace that matched. Reviewing matches requires permission to view run inputs and outputs. A toolbar at the top of the view shows the description, the result’s match confidence, and Evidence N of M. LangSmith highlights each matched message and labels it Evidence N of M. The count includes only the matches LangSmith can locate in the conversation. Matches it cannot locate, for example a message the Trajectory view does not display or text that repeats in the conversation, are not shown. Use the up and down arrows in the toolbar to move between matches, and the icon to leave evidence mode.AI search limitations
- Saved views: A filter that includes AI search cannot be saved as a view. Exit AI search and remove the AI condition to save the remaining filters. Selecting a saved view clears AI search.
- Links: The AI search description is not stored in the page URL, so a copied link does not include it.
- Recents: Filters that include AI search do not appear under Recents in the search bar’s suggestion list.
- Stats: The Stats panel shows Stats unavailable for AI search, and the Shortcuts panel hides value counts. To remove the AI condition and restore stats, click Clear AI filters in the Stats panel.
- Rate limits: AI search requests are rate limited per workspace.
What AI search matches
The AI condition of a search operates on the trajectory: the ordered list of human, AI, and tool messages that LangSmith builds from a trace. It matches the conversational part of your description against each trajectory, then returns the threads, traces, or runs whose associated trajectory matched. LangSmith builds trajectory messages from LLM runs, so an AI condition over runs returns only LLM runs. A filter on the run itself for another run type, such asrun_type:tool with the Single run scope, returns no results. An Any run filter still works, because it matches other runs in the trace.
The AI condition reads only the trajectory. Conditions on things the trajectory does not contain, such as run status, cost, latency, or turn count, become structured filters instead. Check Showing results for: to confirm a condition was applied as a filter; if it was not, write it as a query, for example status:error or name:docs_agent.
The AI condition reads the main agent’s conversation. It does not read the content of subagent, middleware, or compaction messages, so it cannot match a description against what happened inside them.
If AI search does not return a thread, trace, or run you expect, check the time range and the filters listed under Showing results for:, which apply alongside the AI condition. If neither excludes it, LangSmith may not have parsed its trace into a trajectory correctly.
Enable AI search
AI search is off until an organization admin enables it. It runs on LangChain-managed inference, so no model provider API key is required. Enabling it applies to every member of the organization. Enabling AI search confirms that you are authorized to allow your organization’s trace data to be transferred to and processed in the United States, including by LangChain’s subprocessors, and that you understand the hosting and data residency implications. Enabling AI search from organization settings requires organization admin permissions. To enable it:- Go to Settings > AI search in your organization settings.
- Turn on Enable AI search.
- Organization admins: Click Enable AI search. The AI search field then accepts a description.
- Other members: Click Ask an admin to enable AI search. LangSmith emails the organization admins, and the dialog confirms that the request was submitted.
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.
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:llmin 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.
See also
- View traces
- Threads
- Add metadata and tags to traces
- Trace query syntax for the SDK and REST API query language
- Query traces using the SDK
Connect these docs to your agent of choice via MCP for real-time answers.

