> ## 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 and Evaluate Trace

> Create a trace and immediately evaluate it against specified metrics in a single call.

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

## Returns

Returns a tuple containing:

1. A [Trace](https://docs.galtea.ai/v5.13/concepts/product/version/session/trace.md) object
2. A list of [Evaluation](https://docs.galtea.ai/v5.13/concepts/product/version/session/evaluation.md) objects, one for each metric evaluated

## Usage

This method combines creating a trace with its evaluation in a single convenient call. It's the recommended approach for single-turn evaluations, replacing the deprecated `galtea.evaluations.create_single_turn()` method.

### Basic Example

Evaluate by passing [Specification](https://docs.galtea.ai/v5.13/concepts/product/specification.md) IDs so the API resolves their linked metrics automatically (recommended), or by listing metric names explicitly.

> [tab] Using specification IDs
>
> ```python theme={"system"}
> # Evaluate using metrics linked to specifications (no need to list metrics manually)
> trace, evaluations = galtea.traces.create_and_evaluate(
>     session_id=session_id,
>     input="What is the capital of France?",
>     output="The capital of France is Paris.",
>     specification_ids=[specification.id],
> )
> ```

> [tab] Using metrics
>
> ```python theme={"system"}
> # Create trace and evaluate in a single call
> trace, evaluations = galtea.traces.create_and_evaluate(
>     session_id=session_id,
>     input="What is the capital of France?",
>     output="The capital of France is Paris.",
>     metrics=[{"name": "Factual Accuracy"}, {"name": "Answer Relevancy"}],
> )
> ```

### With Pre-computed Scores

```python theme={"system"}
# With pre-computed scores for self-hosted metrics
trace, evaluations = galtea.traces.create_and_evaluate(
    session_id=session_id,
    output="Model response...",
    metrics=[
        {"name": "Factual Accuracy"},
        {"name": self_hosted_metric.name, "score": 0.95},  # Pre-computed score
    ],
)
```

### With Custom Score Calculation

```python theme={"system"}
# With dynamic score calculation using CustomScoreEvaluationMetric
from galtea import CustomScoreEvaluationMetric


class MyMetric(CustomScoreEvaluationMetric):
    def measure(self, *args, actual_output: str | None = None, **kwargs) -> float:
        # Your custom scoring logic
        return 0.95


custom_metric = MyMetric(name=self_hosted_metric.name)

trace, evaluations = galtea.traces.create_and_evaluate(
    session_id=session_id,
    output="Model response...",
    metrics=[
        {"name": "Factual Accuracy"},
        {"score": custom_metric},  # Dynamic score calculation
    ],
)
```

## 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.13/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 log and evaluate a turn in one call. 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`. If both anchors 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.13/sdk/api/session/service.md).

**output** `string | object`

The generated output/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.

Required unless `output_file_paths` carries the whole answer. Give one of the two, or the call raises a `ValueError`.

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

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.13/sdk/api/trace/upload-output-file.md) for the list and for reusing one upload across turns.

A custom scoring function still receives the text of the output, never the files.

> [!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.

**metrics** `list[str | CustomScoreEvaluationMetric | dict]`

A list of metrics to evaluate against. Supports multiple formats:

* Strings: Metric names (e.g., `["accuracy", "relevance"]`)
* CustomScoreEvaluationMetric: Objects with dynamic score calculation. Must be initialized with either 'name' or 'id' parameter.
* MetricInput dicts: Format with optional id, name, and score.
  * If `score` is a `float`: Pre-calculated score (requires 'id' or 'name' in the dict).
  * If `score` is a `CustomScoreEvaluationMetric`: Dynamic score calculation.

Optional when `specification_ids` is provided (in which case metrics are resolved from the specifications).

**specification\_ids** `list[str]`

A list of [Specification](https://docs.galtea.ai/v5.13/concepts/product/specification.md) IDs. When provided, the evaluation uses the metrics linked to these specifications.

Can be combined with `metrics` — the API merges and deduplicates by metric ID.

> [!NOTE]
>
> This parameter allows you to evaluate against specific product specifications without manually listing all their associated metrics. At least one of `metrics` or `specification_ids` must be provided.

**input** `string | object`

The input text/prompt. If not provided, will be inferred from the test case linked to the session. 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.

On a dataset session with no `input`, the files are added to the test case input. A production session accepts files with no `input`: the input is then the files alone. A production session with neither raises a `ValueError`. With `session_custom_id` and only a `product_id`, also pass `input`.

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.13/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.

**retrieval\_context** `string`

Context retrieved by a RAG system, if applicable.

**latency** `float`

Latency in milliseconds from model invocation to response.

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

Token usage information from the model call.
Supported keys: `input_tokens`, `output_tokens`, `cache_read_input_tokens`.

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

Cost breakdown for the model call.
Supported keys: `cost_per_input_token`, `cost_per_output_token`, `cost_per_cache_read_input_token`.

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

Version of Galtea's conversation simulator used to generate the input.

**run\_id** `string`

The [Run](https://docs.galtea.ai/v5.13/concepts/product/run.md) the evaluations join. Defaults to the run of the enclosing `galtea.runs.start()` block, when there is one. An explicit value wins over the block.

## Related

* [Create Evaluation](https://docs.galtea.ai/v5.13/sdk/api/evaluation/create.md) - Evaluate an existing session or trace
* [Create Trace](https://docs.galtea.ai/v5.13/sdk/api/trace/create.md) - Create a trace without immediate evaluation
* [Upload Output File](https://docs.galtea.ai/v5.13/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.