> ## 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.

# 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>