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 and can optionally include metadata like latency, token usage, cost, and retrieval context (for RAG evaluations). You can create traces from the Galtea dashboard (using Endpoint Connections) or programmatically using the Galtea SDK.This entity was called Inference Result before SDK 5.0.0, and
galtea.traces used to mean what
is now a Span. See
Dataset, Trace, and Span Renames for what to change in
your code.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 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
Trace Service SDK
Manage traces using the Python SDK
Trace Properties
Session
required
The session to which the trace belongs.
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.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, Update Trace or Create and Evaluate Trace. 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() or galtea.storage.read(). An agent callback receives the same objects as input_data.input_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.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.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.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() or galtea.storage.read().Attach them by naming local paths in output_file_paths on Create Trace, Update Trace or Create and Evaluate Trace. An agent callback answers with files through AgentResponse.output_file_paths. To reuse one upload across turns, call galtea.traces.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.One output accepts at most 20 files, 20 MB in total, of the same types an input accepts.Retrieval context is not a stored field on the trace. It is derived from the trace’s
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.float
The latency in milliseconds for the model’s response.
dict
Token usage information for the trace.
dict
Cost information for the trace.
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 instead. The dashboard shows the count on the trace so you do not have to read a log to learn a span is missing.
string
The W3C trace ID that Galtea sends to your endpoint in the
traceparent header on this Direct Inference 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
Concepts overview
How Galtea’s concepts connect — diagram + per-entity quick reference.
Session
The conversation that groups traces together.
Evaluation
Score traces using metrics.
Span
Capture internal operations linked to traces.