> ## 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.

# Update Trace

> Update an existing trace with agent output and metadata

> [!WARNING]
>
> You are reading the docs of Galtea 5.17. [Read this page in the latest version](https://docs.galtea.ai/sdk/api/trace/update.md).

## 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

**trace\_id** `string` *required*

The ID of the trace to update.

### Input Fields

**input** `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](https://docs.galtea.ai/v5.17/concepts/product/version/session/content-parts.md).

**input\_file\_paths** `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](https://docs.galtea.ai/v5.17/sdk/api/trace/upload-output-file.md) for the list.

> [!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.17/concepts/product/version/session/content-parts.md#galtea-files), 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](https://docs.galtea.ai/v5.17/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.17/concepts/metric/evaluation-parameters.md#troubleshooting-skipped-evaluations).

### Output Fields

**output** `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](https://docs.galtea.ai/v5.17/concepts/product/version/session/content-parts.md).

**output\_file\_paths** `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](https://docs.galtea.ai/v5.17/sdk/api/trace/upload-output-file.md) for the list and for reusing one upload across turns.

Output files follow the same rule as `input_file_paths` above.

**retrieval\_context** `string`

The context retrieved by a RAG system, if applicable.

> [!NOTE]
>
> 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

**latency** `float`

The time in milliseconds from request to response.

### Usage Fields

**input\_tokens** `int`

Number of input tokens sent to the model, cached input included.

**output\_tokens** `int`

Number of output tokens generated by the model.

**cache\_read\_input\_tokens** `int`

Number of input tokens read from the cache. They are part of the input tokens.

**tokens** `int`

Total tokens used in the model call. Cached input counts once.

### Cost Fields

**cost** `float`

The total cost associated with the model call.

**cost\_per\_input\_token** `float`

Cost per input token sent to the model.

**cost\_per\_output\_token** `float`

Cost per output token generated by the model.

**cost\_per\_cache\_read\_input\_token** `float`

Cost per input token read from the cache.

Once the turn's spans report token usage, the span prices replace a per-token price sent on the turn. Send `cost` 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 updated `Trace` object.

## Example

```python theme={"system"}
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:

```python theme={"system"}
# 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:

```python theme={"system"}
galtea.traces.update(
    trace_id=trace.id,
    cost=0.0025,
    cost_per_input_token=0.00001,
    cost_per_output_token=0.00003,
)
```

## Notes

> [!NOTE]
>
> 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

## Related Methods

* [Create Trace](https://docs.galtea.ai/v5.17/sdk/api/trace/create.md) - Create a new trace
* [Generate Trace](https://docs.galtea.ai/v5.17/sdk/api/trace/generate.md) - Create with automatic span collection
* [Get Trace](https://docs.galtea.ai/v5.17/sdk/api/trace/get.md) - Retrieve a trace
* [Upload Output File](https://docs.galtea.ai/v5.17/sdk/api/trace/upload-output-file.md) - Upload one file and reuse it across turns


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.