> ## 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.17. [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.17/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.17/concepts/product/endpoint-connection.md)) or programmatically using the [Galtea SDK](https://docs.galtea.ai/v5.17/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.17/concepts/product/version/session/span.md). See
> [Dataset, Trace, and Span Renames](https://docs.galtea.ai/v5.17/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.17/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.17/sdk/api/trace/create.md), [Update Trace](https://docs.galtea.ai/v5.17/sdk/api/trace/update.md) or [Create and Evaluate Trace](https://docs.galtea.ai/v5.17/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.17/sdk/api/storage/download) or [`galtea.storage.read()`](https://docs.galtea.ai/v5.17/sdk/api/storage/read), except a [file part of your own](https://docs.galtea.ai/v5.17/concepts/product/version/session/content-parts.md#your-own-parts). An agent callback receives the same objects as [`input_data.input_files`](https://docs.galtea.ai/v5.17/sdk/api/agent/input#reading-attached-files).

One input accepts at most 20 Galtea files, 20 MB in total, of the same types a test case input accepts. Galtea refuses a Galtea file that breaks a rule, and stores every other element of the `content` list as sent. See [Content Parts](https://docs.galtea.ai/v5.17/concepts/product/version/session/content-parts.md).

> [!NOTE]
>
> **A metric scores a file only when its judge model reads that kind of file.** Only a [Galtea file](https://docs.galtea.ai/v5.17/concepts/product/version/session/content-parts.md#galtea-files), one you uploaded to Galtea or one that Galtea stored from inline media, is sent to a judge. A file on your own host is stored as sent and is never sent to a judge as a file, so it never skips an evaluation: the judge reads its entry as JSON text, in its place in the turn. The kinds a judge reads depend on its model, and the model picker of the metric form shows them for each model. A judge is sent PNG, JPEG, WebP, GIF and PDF files only. The other accepted types are stored, and a Galtea input file of those types still reaches your endpoint, but no judge reads them. The rule is the same for the input and the output, and a metric that reads `conversation_turns` reads both sides of every turn. A metric that reads `traces` also reads the Galtea files of every span, and a metric that reads `retrieval_context` reads the Galtea files in the output of `RETRIEVER` spans.
>
> **Galtea numbers the files of a session.** Turn files come first, in turn order, input before output. The files of every span come next, in span start order. A file that sits in several places of a session takes one number, at its first place, and the judge receives it once. The judge reads each file in its place in the text as `[File N]`, and the session page and the span page show the same `File N` beside each Galtea file.
>
> Before an evaluation runs, Galtea checks every Galtea file on each side the metric reads. One file the judge would not read skips the evaluation, whatever text sits beside it. A skipped evaluation costs no credits, and its reason names the file with its number, its turn and what refused it:
>
> * The judge model cannot read that kind of file.
> * The model catalog does not say whether the judge model reads it.
> * The metric names no judge model.
> * The metric is DeepEval-based: those judges are sent text only.
> * The metric is deterministic: it compares text without a model.
> * The metric is a [classifier](https://docs.galtea.ai/v5.17/concepts/metric/classifier.md) metric: it is sent text only.
> * The file is a type no judge reads, such as DOCX, CSV or TIFF, or an audio file: a judge reads audio only through its transcript.
>
> When the evaluator then reads a Galtea file to send it, it skips the evaluation if the file no longer exists in storage, is empty, or is larger than the 20 MB a judge can receive. The reason names the file.
>
> Audio input with no transcript is a separate case. A metric that reads the input is skipped when no turn of the session has input text or a Galtea input file, and a turn's audio carries no transcript. Text or a Galtea file on another turn is enough, and the reason, `Evaluators read an audio input through its transcript, and no turn carries one.`, names no file.
>
> Human evaluation and self-hosted metrics are never skipped for a file or for audio. On deployments that do not send files to the judge, the evaluator also skips a metric whose judge would read the file, and the reason names the file.
>
> To have the content scored, pick a metric whose judge model reads that kind of file, or log the text your pipeline extracted as the turn input or output, without the file. See [Troubleshooting skipped evaluations](https://docs.galtea.ai/v5.17/concepts/metric/evaluation-parameters.md#troubleshooting-skipped-evaluations).

> [!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.17/sdk/api/storage/download) or [`galtea.storage.read()`](https://docs.galtea.ai/v5.17/sdk/api/storage/read), except a [file part of your own](https://docs.galtea.ai/v5.17/concepts/product/version/session/content-parts.md#your-own-parts).

Attach them by naming local paths in `output_file_paths` on [Create Trace](https://docs.galtea.ai/v5.17/sdk/api/trace/create.md), [Update Trace](https://docs.galtea.ai/v5.17/sdk/api/trace/update.md) or [Create and Evaluate Trace](https://docs.galtea.ai/v5.17/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.17/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.17/concepts/product/endpoint-connection-configuration.md#files-in-the-response).

One output accepts at most 20 Galtea files, 20 MB in total, of the same types an input accepts. Galtea refuses a Galtea file that breaks a rule, and stores every other element of the `content` list as sent. See [Content Parts](https://docs.galtea.ai/v5.17/concepts/product/version/session/content-parts.md).

Output files follow the same rule as [Input Files](#param-input-files): a metric scores a file only when its judge model reads that kind of file.

> [!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.17/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.

**inputTokens, outputTokens, cacheReadInputTokens, tokens** `int`

Token counts for the trace: input, output, cache-read input and total. The input count includes the cache-read input, and the total is input plus output, plus the cache read when the source counted it apart from the input (a cache read above the input count). They are `null` for a user without the `evaluation.readInference` permission.

**costPerInputToken, costPerOutputToken, costPerCacheReadInputToken, cost, creditsUsed** `float`

The price of one input, output and cache-read token, the total cost, and the credits used. The cost values and `creditsUsed` are `null` for a user without the `evaluation.readInference` permission. See [Roles and permissions](https://docs.galtea.ai/v5.17/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.17/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.17/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.

**End User** `string`

The customer of your agent who sent this turn. It is not a Galtea user. Read-only: OpenTelemetry ingest sets it from the spans of this trace only, so two traces of one session can name different end users. Spans that arrive later fill it while it is empty, and never change a stored value. Null when no span of the trace names one. Spans of an existing Trace, such as a Direct Inference turn, set none. A trace file import never sets it. The [session](https://docs.galtea.ai/v5.17/concepts/product/version/session.md) keeps the first end user of all its traces. See [End user](https://docs.galtea.ai/v5.17/sdk/tutorials/monitor-real-user-traffic-with-opentelemetry.md#end-user-optional).

## Related

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

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

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

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