---
type: concept
x-llmwiki:
  schemaVersion: "0.1"
  contentHash: fefad2f470e1a60a8656261f653ca6b7ac90e7eff222a4e4542bbe72bf1ef82c
  pageDirectory: concepts
  sources:
    - create-and-manage-labeling-sessions-databricks-on-aws.md
  confidence: 0.95
  provenanceState: extracted
  freshnessStatus: unverified
  aliases:
    - add-traces-to-labeling-session
    - ATTLS
    - Add Traces to Labeling Session UI
  citations:
    - file: create-and-manage-labeling-sessions-databricks-on-aws.md
title: Add Traces to Labeling Session
description: The workflow for adding MLflow Traces (via UI selection, search results, or individual trace objects) into a labeling session for expert review.
tags:
  - mlflow
  - traces
  - labeling
  - workflow
timestamp: "2026-06-18T14:51:45.634Z"
---

# Add Traces to Labeling Session

**Add Traces to Labeling Session** refers to the process of associating existing [[MLflow Trace|MLflow Traces]] with a [Labeling Session](/concepts/labeling-session.md) so that domain experts can review and label them using the [MLflow Review App](/concepts/mlflow-review-app.md). After creating a labeling session, you must add traces to it before experts can provide feedback. ^[create-and-manage-labeling-sessions-databricks-on-aws.md]

## Overview

A labeling session acts as a container for traces and their associated labels. Adding traces populates the session with the specific GenAI application interactions that you want experts to evaluate. You can add traces using either the Databricks UI or the `add_traces()` API method. ^[create-and-manage-labeling-sessions-databricks-on-aws.md]

Traces can originate from any instrumented application, including those using [MLflow OpenAI Autolog](/concepts/mlflow-openai-autolog.md) or the `@mlflow.trace` decorator. When adding traces, you can select multiple traces at once or add individual trace objects programmatically. ^[create-and-manage-labeling-sessions-databricks-on-aws.md]

## Prerequisites

Before adding traces, you must:

- Have an existing labeling session (created via UI or API).
- Have traces logged to an MLflow experiment, typically generated by running your GenAI application with tracing enabled.
- (If using the API) Have the MLflow client configured to the correct tracking URI and experiment.

## Add Traces Using the UI

To add traces via the Databricks workspace UI:

1. In the left sidebar, click **Experiments**.
2. Open the experiment containing the traces.
3. Click **Traces** in the sidebar.
4. Select the traces you want to add by checking the box to the left of the Trace ID.
5. From the **Actions** drop-down menu, choose **Add to labeling session**.
6. In the dialog that appears, click **Export** next to the target labeling session, then click **Done**.

^[create-and-manage-labeling-sessions-databricks-on-aws.md]

## Add Traces Using the API

The `add_traces()` method on a `LabelingSession` object accepts either a DataFrame of traces (from `mlflow.search_traces()`) or a list of individual `Trace` objects.

### Add Traces from Search Results

You can use `mlflow.search_traces()` to find traces matching a filter (e.g., by tag or time range) and add them to a session in bulk:

```python
import mlflow.genai.labeling as labeling

# Search for traces with a specific tag
traces_df = mlflow.search_traces(
    filter_string="tags.test_tag = 'C001'",
    max_results=50
)

# Create a labeling session (if not already created)
session = labeling.create_labeling_session(
    name="negative_feedback_review",
    assigned_users=["quality_expert@company.com"],
    label_schemas=["response_quality", "expected_facts"]
)

# Add the traces from the search results
session.add_traces(traces_df)
print(f"Added {len(traces_df)} traces to session")
```

^[create-and-manage-labeling-sessions-databricks-on-aws.md]

### Add Individual Trace Objects

If you have specific trace IDs, you can retrieve the `Trace` objects with `mlflow.get_trace()` and add them individually:

```python
import mlflow.genai.labeling as labeling

# Generate some traces (e.g., with @mlflow.trace)
# ... (code to generate traces and capture trace IDs)

# Retrieve trace objects by ID
trace1 = mlflow.get_trace(trace_id_1)
trace2 = mlflow.get_trace(trace_id_2)

# Create session and add individual traces
session = labeling.create_labeling_session(
    name="edge_case_review",
    assigned_users=["expert@company.com"],
    label_schemas=["response_quality"]
)
session.add_traces([trace1, trace2])
```

^[create-and-manage-labeling-sessions-databricks-on-aws.md]

> **Note:** For details on how traces are rendered and displayed to labelers in the Review App UI — including how dictionaries, OpenAI message formats, and tool calls are presented — see the [Review App content rendering](https://docs.databricks.com/aws/en/mlflow3/genai/human-feedback/expert-feedback/label-existing-traces#rendering) documentation. ^[create-and-manage-labeling-sessions-databricks-on-aws.md]

## Best Practices

- **Batch size**: Add up to 25–100 traces per session to avoid reviewer fatigue. ^[create-and-manage-labeling-sessions-databricks-on-aws.md]
- **Use clear filters**: When searching for traces, apply relevant tags or time ranges to select a focused set for review.
- **Store the session run ID**: After creating a session, save `session.mlflow_run_id` for reliable programmatic access, since session names may not be unique. ^[create-and-manage-labeling-sessions-databricks-on-aws.md]
- **Ensure tracing is enabled**: Use `mlflow.openai.autolog()` or explicit `@mlflow.trace` decorators to capture traces before adding them. ^[create-and-manage-labeling-sessions-databricks-on-aws.md]

## Related Concepts

- [Labeling Sessions](/concepts/labeling-sessions.md) — Container for traces and expert labels
- [[MLflow Trace|MLflow Traces]] — Record of a GenAI application interaction
- [Labeling Schemas](/concepts/labeling-schemas.md) — Structured feedback questions for reviewers
- [MLflow Review App](/concepts/mlflow-review-app.md) — UI where experts provide labels
- [MLflow OpenAI Autolog](/concepts/mlflow-openai-autolog.md) — Automatic tracing for OpenAI calls

## Sources

- create-and-manage-labeling-sessions-databricks-on-aws.md

# Citations

1. [create-and-manage-labeling-sessions-databricks-on-aws.md](/references/create-and-manage-labeling-sessions-databricks-on-aws-6716f1fc.md)
