---
title: Full-Text Search
description: Find content across the inputs, outputs, and metadata of your traces and observations with full-text search in Langfuse.
sidebarTitle: Full-Text Search
---

# Full-Text Search

Full-text search lets you find all occurrences of a specific keyword or phrase across the inputs, outputs, and metadata of your traces and observations. This is especially useful when debugging complex applications where you remember a piece of content but not which trace it belongs to.

## Search in the UI

Use the search bar above the traces and observations tables to search across `input` and `output` content. Matching traces and observations are returned so you can quickly locate the run you are looking for and combine search with the existing filters and time range selectors.

On the v4 Observations and Traces tables, full-text search is also available inline in the [Filter Search Bar](/docs/observability/features/filter-search-bar), alongside structured filters like `level:ERROR` and `latency:>2`.

## Performance [#performance]

Search uses [ClickHouse full-text search](https://clickhouse.com/docs/engines/table-engines/mergetree-family/textindexes). Text indexes let Langfuse skip over data that cannot match a query before reading full observation payloads, which keeps search fast even for large projects with high-volume traces. You can read more in the [ClickHouse GA announcement](https://clickhouse.com/blog/full-text-search-ga-release).

Because these indexes are token-based, a query matches whole words rather than substrings within them — `error` matches `error` but not `errors` — and a multi-word query matches as a contiguous phrase.

## Search via the API [#api]

The [Observations API v2](/docs/api-and-data-platform/features/observations-api#v2) supports a `matches` operator for token-based full-text search on `input`, `output`, and string `metadata` filters.

When building filters on `/api/public/v2/observations`, prefer `=` when you know the exact value and `matches` when you want token-based search:

- `matches` is **case-insensitive** for `input` and `output`, so `refund failed` can match `Refund Failed`.
- For metadata filters, `matches` is **case-sensitive** and applies to the string metadata value of the selected key.
- Substring operators such as `contains`, `starts with`, and `ends with` are rejected with `400` on `input` and `output` filters because they would require slow full-content scans. Use `matches` for token search on these fields instead.

Example `matches` filter for observation output:

```json
[
  {
    "type": "string",
    "column": "output",
    "operator": "matches",
    "value": "refund failed"
  }
]
```

Example exact metadata filter:

```json
[
  {
    "type": "stringObject",
    "column": "metadata",
    "key": "environment",
    "operator": "=",
    "value": "production"
  }
]
```

Pass the JSON array as the URL-encoded `filter` query parameter on `GET /api/public/v2/observations`. See the [Observations API v2 docs](/docs/api-and-data-platform/features/observations-api#v2) and the [API reference](https://api.reference.langfuse.com/#tag/observations/GET/api/public/v2/observations) for the full filter schema.

## GitHub Discussions

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/docs/observability/features/full-text-search.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.