Skip to main content
You are reading the docs of Galtea 5.15. Read this page in the latest version.

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.

Input Fields

string | object
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.
list[str]
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, 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 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.

Output Fields

string | object
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.
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 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.
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

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 creditsUsed field cannot be modified through this method