> ## 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.16. [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.16/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.16/concepts/product/endpoint-connection.md)) or programmatically using the [Galtea SDK](https://docs.galtea.ai/v5.16/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.16/concepts/product/version/session/span.md). See
> [Dataset, Trace, and Span Renames](https://docs.galtea.ai/v5.16/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.16/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.16/sdk/api/trace/create.md), [Update Trace](https://docs.galtea.ai/v5.16/sdk/api/trace/update.md) or [Create and Evaluate Trace](https://docs.galtea.ai/v5.16/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.16/sdk/api/storage/download) or [`galtea.storage.read()`](https://docs.galtea.ai/v5.16/sdk/api/storage/read), except a [file part of your own](https://docs.galtea.ai/v5.16/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.16/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.16/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.16/concepts/product/version/session/content-parts.md#galtea-files), one you uploaded to Galtea, is sent to a judge. A file on your own host is stored as sent and never reaches a judge, so it never skips an evaluation: the judge reads the text beside it. 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.
>
> 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, 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.16/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.16/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.16/sdk/api/storage/download) or [`galtea.storage.read()`](https://docs.galtea.ai/v5.16/sdk/api/storage/read), except a [file part of your own](https://docs.galtea.ai/v5.16/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.16/sdk/api/trace/create.md), [Update Trace](https://docs.galtea.ai/v5.16/sdk/api/trace/update.md) or [Create and Evaluate Trace](https://docs.galtea.ai/v5.16/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.16/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.16/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.16/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.16/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. 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.16/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.16/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.16/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.16/concepts/overview.md)
>
> How Galtea's concepts connect — diagram + per-entity quick reference.

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

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

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