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

# Create Trace

> Create a new trace log in a session.

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

## Returns

Returns a [Trace](https://docs.galtea.ai/v5.11/concepts/product/version/session/trace.md) object.

## Example

```python theme={"system"}
trace = galtea.traces.create(
    session_id=session_id,
    input="What is the capital of France?",
    output="Paris",
    latency=150.5,
)
```

### Answering with a file

For a product whose answer is a document, name the local files and the SDK uploads them:

```python theme={"system"}
trace = galtea.traces.create(
    session_id=session.id,
    input="Draft the lease agreement we discussed",
    output="Here is the draft you asked for.",
    output_file_paths=["path/to/lease-agreement.pdf"],
)
```

Leave `output` out when the file is the whole answer:

```python theme={"system"}
document_only = galtea.traces.create(
    session_id=session.id,
    input="Send me the signed copy",
    output_file_paths=["path/to/lease-agreement.pdf"],
)
```

### Reading a document as input

For a product that reads documents, name the local files and the SDK uploads them. Galtea stores each file without its upload signature, so the trace keeps working after the upload link expires:

```python theme={"system"}
trace = galtea.traces.create(
    session_id=session.id,
    input="Who is the tenant in this lease agreement?",
    input_file_paths=["path/to/lease-agreement.pdf"],
    output="The tenant is Marta Ruiz.",
)
```

Leave `input` out when the file is the whole input:

```python theme={"system"}
document_only = galtea.traces.create(
    session_id=session.id,
    input_file_paths=["path/to/lease-agreement.pdf"],
    output="This is a residential lease agreement.",
)
```

## Parameters

**session\_id** `string`

The session ID to log the trace to.

> [!NOTE]
>
> Instead of a `session_id`, you can reference an existing session by its own conversation id (see the section below). Provide exactly one of the two.

> [accordion] Log to an existing session by your own conversation ID
>
> If you already created the session via the [sessions API](https://docs.galtea.ai/v5.11/sdk/api/session/service.md) with your own `custom_id`, reference it here with `session_custom_id` plus a `version_id` or `product_id` to append traces to it. If no matching session exists, the call returns a `400` error — create it first via the sessions API.
>
> **session\_custom\_id** `string`
>
> Your own conversation id, as an alternative to `session_id`. Galtea finds an existing session with this id (per version); the session is not created here. Requires `version_id` or `product_id`.
>
> **version\_id** `string`
>
> The version the session is anchored to when using `session_custom_id`.
>
> > [!NOTE]
> >
> > Provide `version_id` or `product_id` (at least one) when using `session_custom_id`. If both are given, `version_id` wins and `product_id` is ignored.
>
> **product\_id** `string`
>
> Product anchor used when no `version_id` is given with `session_custom_id`: Galtea finds the session with this custom id under the product (across its versions).
>
> > [!NOTE]
> >
> > If no session matches the `session_custom_id` and anchor, the call returns a `400` error. Create the session first via the [sessions API](https://docs.galtea.ai/v5.11/sdk/api/session/service.md).

**input** `string | object`

The input text/prompt. 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** `string | object`

The generated output/response. 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, such as `trace.input_files[0].uri`, which is attached without uploading it again.

`input` stays optional, so a turn can receive files and no text. The input is then the 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.11/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\_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.

`output` stays optional, so a turn can answer with files and no text. Its `actual_output` then reads back as `None`, and the envelope is in `actual_output_data`.

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.11/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`

Context retrieved for RAG systems.

> [!NOTE]
>
> When you set `retrieval_context`, Galtea also records it as a `RETRIEVER` span on this trace.

**latency** `float`

Latency in milliseconds.

**usage\_info** `dict[str, int]`

Information about token usage during the model call.
Possible keys include:

* `input_tokens`: Number of input tokens sent to the model.
* `output_tokens`: Number of output tokens generated by the model.
* `cache_read_input_tokens`: Number of input tokens read from the cache.

**cost\_info** `dict[str, float]`

Information about the cost per token during the model call.
Possible keys include:

* `cost_per_input_token`: Cost per input token sent to the model.
* `cost_per_output_token`: Cost per output token generated by the model.
* `cost_per_cache_read_input_token`: Cost per input token read from the cache.

**conversation\_simulator\_version** `string`

The version of Galtea's conversation simulator used to generate the user message (input). This should only be provided when logging a conversation that was generated using the simulator.

**status** `str | TraceStatus`

The initial status of the trace. Accepts a case-insensitive string or a `TraceStatus` enum value. Valid values: `PENDING`, `GENERATED`, `FAILED`, `SKIPPED`. Other string values are sent to the API unchanged, so values added in newer API versions can be used; the API rejects invalid ones.

The two typical SDK flows are:

* **Omit (default)** to create the trace as `GENERATED` — the right choice when the output is already known at create time.
* **Pass `PENDING`** to log the trace before the model call completes, then transition to `GENERATED` or `FAILED` via [`update()`](https://docs.galtea.ai/v5.11/sdk/api/trace/update) once the call resolves.

Passing `FAILED` or `SKIPPED` directly is supported for callers that want to log a terminal-state trace explicitly (e.g. recording a known-bad turn or a skipped step).


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