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

# Traces API

> Ingest, search, and inspect agent execution traces — the atomic unit of the platform.

A trace is a single complete agent execution: input, LLM calls, tool calls, output. Every other feature (evaluation, compatibility scoring, dataset building) operates on traces. Each trace is auto-tagged with the manifest hash of the agent that produced it — that's what makes the regression check work.

## Lifecycle

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f5f5f4','primaryBorderColor':'#a8a29e','primaryTextColor':'#44403c','lineColor':'#a8a29e'}}}%%
flowchart LR
    A[ingest single] --> S[stored]
    B[batch ingest] --> S
    C[import<br/>bulk historical] --> S
    S --> D[get / show]
    D --> E[evaluate]
    S --> F[search via list]
    S --> G[stats / eval stats]
```

## Common patterns

<CardGroup cols={2}>
  <Card title="Instrument a Python agent" icon="rocket" href="/quickstart">
    Add `decimalai.init(langchain=True)` (or your framework's flag). All trace ingest is then automatic via the SDK — you rarely call `POST /traces` directly.
  </Card>

  <Card title="Search by criteria" icon="magnifying-glass" href="/api-reference/traces/search">
    The `GET /traces` endpoint accepts filters for agent, status, manifest, eval verdict, score range, and full-text search. There's no separate /search endpoint.
  </Card>

  <Card title="Bulk import historical data" icon="upload" href="/api-reference/common-endpoints">
    Migrating from another tool? Use `POST /traces/import-bulk` (or `POST /traces/import` for a JSONL upload). Duplicates are silently skipped — re-running is safe.
  </Card>

  <Card title="Inspect a single trace" icon="microscope" href="/api-reference/common-endpoints">
    `GET /traces/{id}` returns the full span tree, LLM call messages, and tool calls. Pass `include=eval_scores` to fetch quality scores in the same call.
  </Card>
</CardGroup>

## Structure

A trace contains two child types:

| Type          | What it represents                                                                                                        | Examples                                        |
| ------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| **Spans**     | Containers and non-LLM operations. Nest via `parent_span_id`.                                                             | `agent_planning`, `tool_execution`, `retrieval` |
| **LLM calls** | Individual model invocations at full fidelity (prompt, completion, tokens, latency). Link to a parent span via `span_id`. | Each `chat.completions.create()` call           |

See [Execution Model](/concepts/execution-model) for the full data model.

## Quick start

```python theme={null}
import decimalai
decimalai.init(api_key="dai_sk_...", openai_agents=True)

# Traces flow automatically as your agent runs.

# To search:
import httpx
resp = httpx.get(
    "https://api.decimal.ai/api/v1/traces",
    headers={"Authorization": "Bearer dai_sk_..."},
    params={"agent_name": "my-agent", "eval_verdict": "drop", "limit": 20},
)
for t in resp.json()["traces"]:
    print(t["id"], t["eval_score"])
```

## Related

* [Tracing Guide](/guides/tracing) — framework-by-framework setup
* [Execution Model](/concepts/execution-model) — trace, span, LLM call, session
* [Evaluations API](/api-reference/evaluations/overview) — push quality scores to traces
* [Common endpoints](/api-reference/common-endpoints) — every endpoint, including `POST /traces/import` and `/traces/import-bulk`