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

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# Overview

> Search, retrieve, and share LangWatch traces via the REST API. Traces capture the full execution of your LLM pipelines including all spans, evaluations, and metadata.

## Intro

The Traces API lets you search and retrieve traces for your project. Each trace captures a complete LLM pipeline execution, including nested spans (LLM calls, tool calls, RAG retrievals), evaluations, and metadata.

Both search and get-trace endpoints support a `format` parameter:

* **`digest`** (default), Returns an AI-readable formatted trace with hierarchical span tree, timing, inputs/outputs, and errors. Optimized for LLM consumption.
* **`json`**, Returns the full raw trace data with all fields.

For data-team ETL, `POST /api/traces/search` also accepts a **projection DSL**
(`from` + `select`) that returns exactly the fields you ask for — including
nested events, annotations, and evaluations joined server-side — so a daily pull
becomes one paginated loop instead of a per-trace fan-out. It pairs with a
`dateField` option to page by when traces were **last modified** rather than when
they occurred. See [Projection DSL & field catalog](/docs/api-reference/traces/projection-dsl).

## Authentication

Pass your LangWatch API key in the `X-Auth-Token` header. Your API key can be found on the setup page under settings.

## Endpoints

| Method | Path | Description |
| - | - | - |
| `POST` | `/api/traces/search` | Search traces with filters and pagination |
| `GET` | `/api/traces/{traceId}` | Get full trace details by ID |
| `PATCH` | `/api/traces/{traceId}/metadata` | Update trace metadata after creation |
| `GET` | `/api/thread/{id}` | Get all traces in a thread |
| `POST` | `/api/trace/{id}/share` | Create a public share link |
| `POST` | `/api/trace/{id}/unshare` | Remove a public share link |

<Info>
  The older `/api/trace/search` and `/api/trace/{id}` endpoints still work but are deprecated. Migrate to `/api/traces/search` and `/api/traces/{traceId}` for the improved `format` parameter and AI-readable digests.
</Info>


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