Update Trace

Overview

The update() method allows you to modify an existing trace after it has been created. This is useful when you need to add or update output, latency, token usage, or cost information.

Parameters

string

required

The ID of the trace to update.

Output Fields

string | object

The generated output or response from the AI model. A dict is stored as sent, including any content array of file or audio parts; the judge reads only the text beside the parts.

list[str]

Files the turn answers with, for a product whose reply is a document. Each entry is a local path the SDK uploads, or a storage URI from an earlier upload, which is attached without uploading it again.The files are merged into output. An update replaces the whole field, so passing files without an output writes an answer of files alone, and its actual_output then reads back as None.One output accepts at most 20 files, 20 MB in total, of the same types an input accepts. See Upload Output File for the list and for reusing one upload across turns.

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.

string

The input text or prompt for the trace.

string

The context retrieved by a RAG system, if applicable.

When you set retrieval_context, Galtea also records it as a RETRIEVER span on this trace. Sending null (or an empty string) clears the value and removes that span.

Performance Fields

float

The time in milliseconds from request to response.

Usage Fields

int

Number of input tokens sent to the model.

int

Number of output tokens generated by the model.

int

Number of input tokens read from the cache.

int

Total tokens used in the model call.

Cost Fields

float

The total cost associated with the model call.

float

Cost per input token sent to the model.

float

Cost per output token generated by the model.

float

Cost per input token read from the cache.

Returns

Returns the updated Trace object.

Example

trace = galtea.traces.update(
    trace_id=trace_id,
    output="Paris is the capital.",
    cost=0.0001,
)

Use Cases

Deferred Output Update

Create a trace first, then update it after processing completes:

# Create trace with just input
user_input = "What is the weather today?"
trace = galtea.traces.create(session_id=session.id, input=user_input)
if trace is None:
    raise ValueError("trace is None")

# Process with your model
start_time = time.time()
response = my_model_generate(user_input)
latency_ms = (time.time() - start_time) * 1000

# Update with output and metrics
galtea.traces.update(trace_id=trace.id, output=response, latency=latency_ms)

Adding Cost Information

Update a trace with cost data after receiving billing info:

galtea.traces.update(
    trace_id=trace.id,
    cost=0.0025,
    cost_per_input_token=0.00001,
    cost_per_output_token=0.00003,
)

Notes

All fields except trace_id and output_file_paths default to PydanticUndefined (from pydantic_core). Omit a field (or pass PydanticUndefined) to leave it unchanged. Pass None to explicitly clear an optional field. Pass a value to update it.output_file_paths defaults to None and has no clear value. Passing None attaches nothing and leaves the files already on the output untouched.

The creditsUsed field cannot be modified through this method

Create Trace - Create a new trace
Generate Trace - Create with automatic span collection
Get Trace - Retrieve a trace
Upload Output File - Upload one file and reuse it across turns

Introduction

SDK

CLI

Concepts

Overview

Parameters

Output Fields

Performance Fields

Usage Fields

Cost Fields

Returns

Example

Use Cases

Deferred Output Update

Adding Cost Information

Notes

​Overview

​Parameters

​Output Fields

​Performance Fields

​Usage Fields

​Cost Fields

​Returns

​Example

​Use Cases

​Deferred Output Update

​Adding Cost Information

​Notes

​Related Methods

Overview

Parameters

Output Fields

Performance Fields

Usage Fields

Cost Fields

Returns

Example

Use Cases

Deferred Output Update

Adding Cost Information

Notes

Related Methods