> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trace0hq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Natural Language Search

> Search your transactions by describing what you're looking for in plain English.

## Overview

Natural Language Search lets you search your transactions by describing what you're looking for, rather than writing a query. For example:

`failed requests that took longer than 50ms and involved at least one call to DynamoDB`

Trace0 converts your search into a [Trace0QL](https://docs.trace0hq.com/platform/transactions/search/trace0ql.md) query, runs it, returns the matching transactions and shows the generated query in the `Trace0QL` query box to the right:

![Natural Language Search Light](https://mintcdn.com/trace0/L9un5Y7f7K7XbqHw/images/natural-language-search-light.png?fit=max\&auto=format\&n=L9un5Y7f7K7XbqHw\&q=85\&s=e785843d34fcbe6c913082d7948b6f36)

![Trace0QL Light](https://mintcdn.com/trace0/L9un5Y7f7K7XbqHw/images/trace0ql-light.png?fit=max\&auto=format\&n=L9un5Y7f7K7XbqHw\&q=85\&s=8785cc96c4860b543513d6ba5c8ea504)

Because the `Trace0QL` query is shown, you can check that it matches what you meant, and edit it and run it again if it doesn't. A re-run query is run as written, without being converted again.

The environment, service name and time range selected apply to your search, so you don't need to include them in it.

## What you can search for

You can describe anything that [Trace0QL](https://docs.trace0hq.com/platform/transactions/search/trace0ql.md) can express:

| You can describe | e.g. |
| - | - |
| The request | "failed requests that took longer than 50ms", "5xx errors on POST /orders" |
| The calls it made | "called the users DynamoDB table", "made more than 10 postgres queries" |
| How many calls, and which were slow | "two or more calls to KMS where one took longer than 29ms" |
| Third-party APIs | "a call to the GitHub API that took longer than 300ms" |
| Infrastructure | "cold starts in eu-west-1", "errors from pods in the payments namespace" |
| Tags | "the tag user\_id is 123", "tagged with user\_name Dave Jones" |
| Logs | "logged payment declined" |

Durations can be given in any unit (e.g. `250µs`, `29ms`, `1.5 seconds`), and are converted to nanoseconds for you.

## Examples

| Search | Trace0QL |
| - | - |
| duration was greater than 50ms and it failed | `duration > 50000000 AND error = true` |
| the endpoint is /identities/verify | `endpoint contains /identities/verify` |
| the endpoint is POST /identities/verify | `endpoint = "POST /identities/verify"` |
| 5xx errors or timeouts from pods in the payments namespace | `(status_code >= 500 OR exception.type contains timeout) AND k8s.namespace.name = payments` |
| involved a call to KMS that took longer than 29ms | `spans((rpc.service = AWSKMS OR rpc.service = Kms OR rpc.service = KMS) AND span.duration > 29000000) >= 1` |
| made more than 10 postgres queries | `spans(db.system.name = postgresql) > 10` |
| failed without calling S3 | `error = true AND spans(rpc.service = "Amazon S3" OR rpc.service = S3) = 0` |
| failed requests where the orderId tag is ord\_8812 | `error = true AND tag.orderId = ord_8812` |
| requests that logged payment declined | `log contains "payment declined"` |

## Tips

* Be specific about what you're looking for. "slow requests" has to guess what slow means, while "requests that took longer than 2 seconds" doesn't.
* Describe one call with all its properties together, e.g. "a call to KMS that took longer than 29ms". This is converted to a single `spans(...)` condition, so the same call must match all of them.
* Name tags by their key, e.g. "the tag user\_id is 123". Trace0 only searches tags when your search mentions a tag or gives its key, so "requests from Dave" isn't treated as a tag search.
* Name endpoints with their HTTP method (e.g. "POST /orders") to match only that method, or without it (e.g. "/orders") to match any method.
* If a search can't be converted, or the query isn't what you meant, edit the query in the `Trace0QL` query box. Natural language search is a starting point, and `Trace0QL` gives you full control.

## Privacy

Trace0 uses AI to convert your natural language query into a `Trace0QL` query. Only your search text is sent to an LLM to be converted to `Trace0QL`. Your transactions, spans, logs and tag values are not sent to the LLM.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.