# Sessions

A Session groups multiple traces that belong to the **same logical interaction** under a shared `session_id`. Sessions let you replay entire conversations end-to-end, analyze them as a unit, annotate outcomes, and manage related traces together. You can explore sessions for filtering, cohort analysis, debugging, and evaluation at the conversation level.

<div data-with-frame="true"><figure><img src="https://708770081-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1ICwJbq7EJdn5kBgXnQu%2Fuploads%2FJdjhx1y1W5cQ5QIZ9ICD%2FClipboard-20260311-125906-374.gif?alt=media&#x26;token=24861d5f-ee94-454e-937b-1f695bf67dfd" alt=""><figcaption></figcaption></figure></div>

In a customer support scenario, each time a user sends a message and receives a response, that exchange generates its own trace. When the user follows up with clarifying questions or the conversation escalates to a different topic, each of those exchanges creates additional traces. The session ties all of these traces together under a single identifier, capturing the full support ticket from the customer's first message to resolution.

{% hint style="info" %}
The `sessionId` can be any US-ASCII character string less than 200 characters, if it exceeds it will be dropped.
{% endhint %}

### Why Sessions Matter

LLM-powered applications often span multiple requests. A single user conversation might generate dozens of traces across different turns. Without sessions, these traces appear as disconnected events. Sessions provide the **logical grouping** needed to:

* Replay **entire conversations** from start to finish
* Analyze **multi-turn interactions** as a unit
* Annotate outcomes at the **conversation level**
* Compare **session-level metrics** across cohorts
* **Debug issues** that only appear across multiple turns

Click on any session to open the detail view, which displays the complete list of traces in chronological order, session-level scores and annotations, total duration, cost, token usage, and user information.

***

### Creating a Session

To create a session, assign the same `session_id` to multiple traces. There is no separate "create session" call — the session is automatically created the first time a trace references a given `session_id`.

{% tabs %}
{% tab title="Context Manager" %}

```python
session_id = "ticket-2611"
user_id = "user-a"

# First turn: customer reports an issue
with interactiveai.start_as_current_observation(as_type="span", name="support-inquiry") as span:
    span.update_trace(
        session_id=session_id,
        user_id=user_id,
        input={"message": "My order #12345 hasn't arrived yet"},
        tags=["support", "shipping"]
    )
    # Process user request and generate response

# Second turn: customer provides additional details
with interactiveai.start_as_current_observation(as_type="span", name="support-followup") as span:
    span.update_trace(
        session_id=session_id,
        user_id=user_id,
        input={"message": "I ordered it two weeks ago and the tracking still shows pending"}
    )
    # Process user request and generate response

interactiveai.flush()
```

{% endtab %}

{% tab title="@observe Decorator" %}
Use `update_current_trace()` inside a decorated function to set the session and user:

```python
from interactiveai import observe

session_id = "ticket-2611"
user_id = "user-a"

@observe()
def handle_support_turn(message):
    interactiveai.update_current_trace(
        session_id=session_id,
        user_id=user_id,
        tags=["support", "shipping"]
    )
    response = generate_support_response(message)
    return response

@observe(as_type="generation")
def generate_support_response(message):
    return llm.generate(message)

# First turn
handle_support_turn("My order #12345 hasn't arrived yet")

# Second turn
handle_support_turn("I ordered it two weeks ago and the tracking still shows pending")

interactiveai.flush()
```

If your traces have multiple nested observations that all need the same `session_id` and `user_id`, use `propagate_attributes` instead. For details and parameters, see Updating Traces.
{% endtab %}
{% endtabs %}

***

### **Translating Content**

Click the translate icon in the session detail header to enable translation mode. Content is not translated all at once, each trace is translated individually when expanded. Click the icon again to revert all content to the original language.

<div data-with-frame="true"><figure><img src="https://708770081-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1ICwJbq7EJdn5kBgXnQu%2Fuploads%2FtYSUJyPcYv41igbn9zT6%2Fimage.png?alt=media&#x26;token=e1fdce1d-bf3f-4299-9352-c09122c82aff" alt=""><figcaption></figcaption></figure></div>

***

### Properties of a Session

| Property                | Description                                                       |
| ----------------------- | ----------------------------------------------------------------- |
| **Id**                  | Unique session identifier                                         |
| **Created At**          | Timestamp when the first trace was added to the session           |
| **Duration**            | Total time span from first to last trace in the session           |
| **Environment**         | Deployment context like `production`, `staging`, or `development` |
| **User IDs**            | End-users associated with traces in this session                  |
| **Traces**              | Number of traces grouped under this session                       |
| **Input/Output Cost**   | Cost of input/output tokens across all traces in the session      |
| **Total Cost**          | Accumulated cost (input + output) across all traces               |
| **Input/Output tokens** | Number of input/output tokens consumed across all traces          |
| **Total Tokens**        | Total token count (input + output) across all traces              |
| **Usage**               | Breakdown of token consumption by model                           |
| **Trace Tags**          | Aggregated tags from all traces in the session.                   |