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

# Trace

> A single turn in a conversation between a user and an AI system

> [!WARNING]
>
> You are reading the docs of Galtea 5.11. [Read this page in the latest version](https://docs.galtea.ai/concepts/product/version/session/trace.md).

## What is a Trace?

A trace is a single turn in a conversation — one user input paired with one AI output. It belongs to a [session](https://docs.galtea.ai/v5.11/concepts/product/version/session.md) and can optionally include metadata like latency, token usage, cost, and retrieval context (for RAG evaluations).

You can create traces from the [Galtea dashboard](https://platform.galtea.ai/) (using [Endpoint Connections](https://docs.galtea.ai/v5.11/concepts/product/endpoint-connection.md)) or programmatically using the [Galtea SDK](https://docs.galtea.ai/v5.11/sdk/api/trace/service.md).

> [!NOTE]
>
> **This entity was called Inference Result before SDK 5.0.0**, and `galtea.traces` used to mean what
> is now a [Span](https://docs.galtea.ai/v5.11/concepts/product/version/session/span.md). See
> [Dataset, Trace, and Span Renames](https://docs.galtea.ai/v5.11/sdk/migration-guides/entity-renames.md) for what to change in
> your code.

> [!NOTE]
>
> **Two things are called "trace" here.** A Galtea Trace is the turn described on this page, and its
> own id is `id`. An OpenTelemetry trace is a distributed-tracing correlation id, the API field
> `traceId`. The [OpenTelemetry Trace ID](#trace-properties) property below holds that one, not the id
> of this Trace. The dashboard uses the same two names: "Galtea Trace ID" for this turn's id and
> "OpenTelemetry Trace ID" for the correlation id.

## SDK Integration

> [card] [Trace Service SDK](https://docs.galtea.ai/v5.11/sdk/api/trace/service.md)
>
> Manage traces using the Python SDK

## Trace Properties

**Session** `Session` *required*

The session to which the trace belongs.

**Input** `string | object`

The input text or prompt for the trace. For most runs this is a plain string. For phone (voice) runs, when the simulated user's audio was captured, this is a content-parts envelope `{"user_message": "<transcript>", "content": [{"type": "audio", "uri": "...", "transcript": "..."}]}` — the `user_message` field is the canonical scored scalar. Access the envelope via the SDK's `.input_data` field and the spoken transcript via `.input`. A document turn adds `file` parts to `content`, which the Input Files field below lists.

**Input Files** `AttachedFile[]`

The files attached to the input. They come from the test case, or from `input_file_paths` on a trace you log yourself with [Create Trace](https://docs.galtea.ai/v5.11/sdk/api/trace/create.md), [Update Trace](https://docs.galtea.ai/v5.11/sdk/api/trace/update.md) or [Create and Evaluate Trace](https://docs.galtea.ai/v5.11/sdk/api/trace/create-and-evaluate.md). Galtea stores each file without its upload signature. Read them with the SDK's `.input_files` field, which returns one `AttachedFile` per attached file, ready for [`galtea.storage.download()`](https://docs.galtea.ai/v5.11/sdk/api/storage/download) or [`galtea.storage.read()`](https://docs.galtea.ai/v5.11/sdk/api/storage/read). An agent callback receives the same objects as [`input_data.input_files`](https://docs.galtea.ai/v5.11/sdk/api/agent/input#reading-attached-files).

One input accepts at most 20 files, 20 MB in total, of the same types a test case input accepts. Galtea refuses a file that breaks a rule.

> [!WARNING]
>
> Evaluators cannot read input files yet. A metric that reads the input is **skipped** when no turn of the session has input text without a file, with the reason `Evaluators cannot read input files yet.` One turn with text of its own is enough, so an attachment on one turn of a long session does not skip the rest. Log the text your pipeline extracted from the document as the turn input, without the file, to have it scored. See [File inputs](https://docs.galtea.ai/v5.11/concepts/product/dataset/test-case.md#file-inputs).

> [!NOTE]
>
> `AttachedFile` used to be called `InputFile`, back when only an input could carry files. The same four fields now describe a file on either side. `InputFile` still works as a name for it, so code you already wrote keeps running, but it now warns with a `GalteaDeprecationWarning`. Switch to `AttachedFile` when you next touch that code.

**Output** `string | object`

The generated output or response for the trace. For most runs this is a plain string.

It becomes a content-parts envelope, `{"assistant_message": "<text>", "content": [...]}`, when the turn answers with more than text. The `content` list holds one part per attachment: an `audio` part for a phone (voice) run whose agent audio was captured, or a `file` part for a product whose answer is a document. The `assistant_message` field is the canonical scored scalar.

A document answer may carry no `assistant_message` at all, because the file is the whole answer. The SDK's `.actual_output` is then `None`. Read the envelope through `.actual_output_data` in every case, and the scored text through `.actual_output`.

**Output Files** `AttachedFile[]`

The files the turn answered with, for a product whose reply is a document: a generated report, a filled form, a redacted contract. Read them with the SDK's `.actual_output_files` field, which returns one `AttachedFile` per attached file, ready for [`galtea.storage.download()`](https://docs.galtea.ai/v5.11/sdk/api/storage/download) or [`galtea.storage.read()`](https://docs.galtea.ai/v5.11/sdk/api/storage/read).

Attach them by naming local paths in `output_file_paths` on [Create Trace](https://docs.galtea.ai/v5.11/sdk/api/trace/create.md), [Update Trace](https://docs.galtea.ai/v5.11/sdk/api/trace/update.md) or [Create and Evaluate Trace](https://docs.galtea.ai/v5.11/sdk/api/trace/create-and-evaluate.md). An agent callback answers with files through `AgentResponse.output_file_paths`. To reuse one upload across turns, call [`galtea.traces.upload_output_file()`](https://docs.galtea.ai/v5.11/sdk/api/trace/upload-output-file) and build the envelope yourself.

On a run Galtea makes through an endpoint connection, the files come from the response instead: the connection's `output_files` key names them, and Galtea stores a copy of each, or links a file already in Galtea. See [Files in the Response](https://docs.galtea.ai/v5.11/concepts/product/endpoint-connection-configuration.md#files-in-the-response).

One output accepts at most 20 files, 20 MB in total, of the same types an input accepts.

> [!WARNING]
>
> Evaluators cannot read output files yet. A metric that reads the output is **skipped** when no turn of the session answered with text of its own, counting neither a file nor a note sent beside one, with the reason `Evaluators cannot read output files yet.` One turn carrying text of its own is enough, so an attachment on one turn of a long session does not skip the rest. Log the text your pipeline produced as the turn output, without the file, to have it scored. This mirrors the input side; see [File inputs](https://docs.galtea.ai/v5.11/concepts/product/dataset/test-case.md#file-inputs).

> [!NOTE]
>
> Retrieval context is not a stored field on the trace. It is derived from the trace's
> [`RETRIEVER` spans](https://docs.galtea.ai/v5.11/concepts/product/version/session/span#retrieval-context-in-retriever-spans).
> You can still supply `retrieval_context` when logging (on create, update, or an agent response); Galtea
> records it as a `RETRIEVER` span.
>
> If your agent already emits spans, we recommend sending `RETRIEVER` spans directly instead. This keeps
> one source of truth and lets you capture several retrieval steps per turn, which a single
> `retrieval_context` value cannot.

**Latency** `float`

The latency in milliseconds for the model's response.

**Usage Info** `dict`

Token usage information for the trace.

**Cost Info** `dict`

Cost information for the trace.

**Dropped Span Count** `int`

How many spans sent with this trace were not stored. Empty when none were. A span is dropped when its data is invalid, for example an empty name or a negative latency, and each drop adds to this count as more spans arrive. An unrecognized span **type** never causes a drop; Galtea [normalizes it](https://docs.galtea.ai/v5.11/concepts/product/version/session/span.md#span-types) instead. The dashboard shows the count on the trace so you do not have to read a log to learn a span is missing.

**OpenTelemetry Trace ID** `string`

The W3C trace ID that Galtea sends to your endpoint in the `traceparent` header on this [Direct Inference](https://docs.galtea.ai/v5.11/concepts/product/endpoint-connection.md) turn. Galtea stores it when the turn starts. This is the OpenTelemetry trace id, not the id of this Trace, which is `id`. It lets you correlate the turn with your OTEL-instrumented service. Present on every conversation turn that Galtea generates through an HTTP endpoint connection (Direct Inference), including turns that failed. Phone and WebRTC turns do not have it.

## Related

> [card] [Concepts overview](https://docs.galtea.ai/v5.11/concepts/overview.md)
>
> How Galtea's concepts connect — diagram + per-entity quick reference.

> [card] [Session](https://docs.galtea.ai/v5.11/concepts/product/version/session.md)
>
> The conversation that groups traces together.

> [card] [Evaluation](https://docs.galtea.ai/v5.11/concepts/product/version/session/evaluation.md)
>
> Score traces using metrics.

> [card] [Span](https://docs.galtea.ai/v5.11/concepts/product/version/session/span.md)
>
> Capture internal operations linked to traces.


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