> ## 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.12. [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.12/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, so an attachment on one turn of a long session does not skip the rest. 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.12/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, 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.

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