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

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

<ParamField path="trace_id" type="string" required>
  The ID of the trace to update.
</ParamField>

### Output Fields

<ParamField path="output" type="string">
  The generated output or response from the AI model.
</ParamField>

<ParamField path="input" type="string">
  The input text or prompt for the trace.
</ParamField>

<ParamField path="retrieval_context" type="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.</Note>
</ParamField>

### Performance Fields

<ParamField path="latency" type="float">
  The time in milliseconds from request to response.
</ParamField>

### Usage Fields

<ParamField path="input_tokens" type="int">
  Number of input tokens sent to the model.
</ParamField>

<ParamField path="output_tokens" type="int">
  Number of output tokens generated by the model.
</ParamField>

<ParamField path="cache_read_input_tokens" type="int">
  Number of input tokens read from the cache.
</ParamField>

<ParamField path="tokens" type="int">
  Total tokens used in the model call.
</ParamField>

### Cost Fields

<ParamField path="cost" type="float">
  The total cost associated with the model call.
</ParamField>

<ParamField path="cost_per_input_token" type="float">
  Cost per input token sent to the model.
</ParamField>

<ParamField path="cost_per_output_token" type="float">
  Cost per output token generated by the model.
</ParamField>

<ParamField path="cost_per_cache_read_input_token" type="float">
  Cost per input token read from the cache.
</ParamField>

## 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` 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.
</Note>

* The `creditsUsed` field cannot be modified through this method

## Related Methods

* [Create Trace](/sdk/api/trace/create) - Create a new trace
* [Generate Trace](/sdk/api/trace/generate) - Create with automatic span collection
* [Get Trace](/sdk/api/trace/get) - Retrieve a trace