> ## 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.14. [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, including any `content` array of file or audio parts, except a Galtea file in that array: it is stored without its upload signature and checked like a test case input file (at most 20 files and 20 MB, a type a judge can read, a file of your organization), and the call fails with a `400` when it breaks a rule. A URL outside Galtea storage is kept as sent only when no Galtea file sits in the same `content` array. The judge reads only the text beside the parts.

**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 storage URI from an earlier upload, which is attached without uploading it again.

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.14/sdk/api/trace/upload-output-file.md) for the list.

> [!WARNING]
>
> Evaluators cannot read input files yet. A metric that reads the input is **skipped** when no turn of the session has input text without a file, with the reason `Evaluators cannot read input files yet.` One turn with text of its own is enough for this API check. On deployments that do not send files to the judge, the evaluator also skips LLM-as-a-judge metrics other than the DeepEval-based ones. It does so when any turn the metric reads carries an input file, and the reason names the file. Log the text your pipeline extracted from the document as the turn input, without the file, to have it scored.

### Output Fields

**output** `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, except a Galtea file in that array: it is stored without its upload signature and checked like a test case input file (at most 20 files and 20 MB, a type a judge can read, a file of your organization), and the call fails with a `400` when it breaks a rule. A URL outside Galtea storage is kept as sent only when no Galtea file sits in the same `content` array. The judge reads only the text beside the parts.

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

> [!WARNING]
>
> 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 for this API check. On deployments that do not send files to the judge, the evaluator also skips LLM-as-a-judge metrics other than the DeepEval-based ones. It does so when any turn the metric reads carries an output file, and the reason names the file. Log the text your pipeline produced as the turn output, without the file, to have it scored.

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

**output\_tokens** `int`

Number of output tokens generated by the model.

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

Number of input tokens read from the cache.

**tokens** `int`

Total tokens used in the model call.

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

## 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.14/sdk/api/trace/create.md) - Create a new trace
* [Generate Trace](https://docs.galtea.ai/v5.14/sdk/api/trace/generate.md) - Create with automatic span collection
* [Get Trace](https://docs.galtea.ai/v5.14/sdk/api/trace/get.md) - Retrieve a trace
* [Upload Output File](https://docs.galtea.ai/v5.14/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.