> ## 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.14. [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.14/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.14/concepts/product/endpoint-connection.md)) or programmatically using the [Galtea SDK](https://docs.galtea.ai/v5.14/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.14/concepts/product/version/session/span.md). See
> [Dataset, Trace, and Span Renames](https://docs.galtea.ai/v5.14/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.14/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. Evaluations score the `user_message` together with any other key you add beside `content`. When `user_message` is empty, the audio transcript takes its place. A `{"type": "text"}` part in `content`, the shape OpenAI-style messages use, is scored as text after `user_message`, unless it repeats it. The judge cannot hear a turn whose audio has no transcript and no `user_message`, so a metric that reads the input is skipped when no turn of the session has text. 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.14/sdk/api/trace/create.md), [Update Trace](https://docs.galtea.ai/v5.14/sdk/api/trace/update.md) or [Create and Evaluate Trace](https://docs.galtea.ai/v5.14/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.14/sdk/api/storage/download) or [`galtea.storage.read()`](https://docs.galtea.ai/v5.14/sdk/api/storage/read). An agent callback receives the same objects as [`input_data.input_files`](https://docs.galtea.ai/v5.14/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 for this API check. On deployments that do not send files to the judge, the evaluator also skips LLM-as-a-judge metrics other than the DeepEval-based ones. It does so when any turn the metric reads carries an input file, and the reason names the file. 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.14/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. Evaluations score it together with any other key you add beside `content`, and with the text of any `{"type": "text"}` part.

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`, unless a `{"type": "text"}` part carries text. Read the envelope through `.actual_output_data` in every case, and the output 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.14/sdk/api/storage/download) or [`galtea.storage.read()`](https://docs.galtea.ai/v5.14/sdk/api/storage/read).

Attach them by naming local paths in `output_file_paths` on [Create Trace](https://docs.galtea.ai/v5.14/sdk/api/trace/create.md), [Update Trace](https://docs.galtea.ai/v5.14/sdk/api/trace/update.md) or [Create and Evaluate Trace](https://docs.galtea.ai/v5.14/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.14/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.14/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 for this API check. On deployments that do not send files to the judge, the evaluator also skips LLM-as-a-judge metrics other than the DeepEval-based ones. It does so when any turn the metric reads carries an output file, and the reason names the file. 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.14/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.14/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. `null` for a user without the `evaluation.readInference` permission.

**Usage Info** `dict`

Token usage information for the trace. The token counts are `null` for a user without the `evaluation.readInference` permission.

**Cost Info** `dict`

Cost information for the trace. The cost values and `creditsUsed` are `null` for a user without the `evaluation.readInference` permission. See [Roles and permissions](https://docs.galtea.ai/v5.14/security/roles-and-permissions.md).

**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.14/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.14/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.14/concepts/overview.md)
>
> How Galtea's concepts connect — diagram + per-entity quick reference.

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

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

> [card] [Span](https://docs.galtea.ai/v5.14/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.