Overview
Theupdate() 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
Input Fields
The input text or prompt for the trace. A dict is stored as sent. Galtea reads each element of its
content list on its own: a Galtea file is stored without its upload signature and must be an accepted type, with at most 20 files and 20 MB. Every other element, such as a file URL on your own host, is stored as sent. A Galtea file of another organization fails the call with a 400. A metric scores a Galtea file only when its judge model reads that kind of file. See Content Parts.Files the turn received, for a product that reads documents. Each entry is a local path the SDK uploads, or a Galtea file reference from an earlier upload, which is attached without uploading it again. Any other URL raises a
ValueError before anything is uploaded.The files are merged into input. An update replaces the whole field, so passing files without an input writes an input of files alone.One input accepts at most 20 files, 20 MB in total, of the same types a test case input accepts. See Upload Output File for the list.A metric scores a file only when its judge model reads that kind of file. Only a Galtea file, 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 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.
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.Output Fields
The generated output or response from the AI model. A dict is stored as sent. Galtea reads each element of its
content list on its own: a Galtea file is stored without its upload signature and must be an accepted type, with at most 20 files and 20 MB. Every other element, such as a file URL on your own host, is stored as sent. A Galtea file of another organization fails the call with a 400. A metric scores a Galtea file only when its judge model reads that kind of file. See Content Parts.Files the turn answers with, for a product whose reply is a document. Each entry is a local path the SDK uploads, or a Galtea file reference from an earlier upload, which is attached without uploading it again. Any other URL raises a
ValueError before anything is uploaded.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.Output files follow the same rule as input_file_paths above.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
Usage Fields
Cost Fields
Once the turn’s spans report token usage, the span prices replace a per-token price sent on the turn. Sendcost to keep your own figure.
A request that sends cost stores it. A request that sends token counts or per-token prices, and no cost, derives the cost again from them. A request that sends only the input, the output or tokens keeps a cost that is a sum over spans or one you stated.
Returns
Returns the updatedTrace object.
Example
Use Cases
Deferred Output Update
Create a trace first, then update it after processing completes:Adding Cost Information
Update a trace with cost data after receiving billing info:Notes
All fields except
trace_id, input_file_paths 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.input_file_paths and output_file_paths default to None and have no clear value. Passing None attaches nothing
and leaves the files already on the input or the output untouched.- The
creditsUsedfield cannot be modified through this method
Related Methods
- 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