Session Tracking

Group related LLM requests to track multi-turn conversations and user workflows

What are Sessions?

Sessions allow you to group related LLM requests together to understand multi-turn conversations, user workflows, and sequential operations. Track the entire journey of a user interaction across multiple API calls.

Why Use Sessions?

Conversation Tracking

Group chat messages to analyze full conversations

Workflow Monitoring

Track multi-step AI workflows from start to finish

User Journeys

Understand how users navigate through your AI features

Cost Analysis

Calculate total costs for entire sessions

Session Headers

Add session headers to your requests to group them:

Required Headers

Helicone-Session-Id · string · required

Unique identifier for the session. Use the same ID for all requests in a session.

Optional Headers

Helicone-Session-Name · string

Human-readable name for the session (e.g., “Customer Support Chat”, “Travel Planner”)

Helicone-Session-Path · string

Path or step within the session (e.g., “/booking/flight/search”, “/chat/message/3”)

Basic Example

Python

from openai import OpenAI
import uuid

client = OpenAI(
    api_key="YOUR_OPENAI_KEY",
    base_url="https://oai.helicone.ai/v1",
    default_headers={
        "Helicone-Auth": "Bearer YOUR_HELICONE_KEY"
    }
)

# Generate session ID (same for all requests in this conversation)
session_id = str(uuid.uuid4())

# First message
response1 = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
    extra_headers={
        "Helicone-Session-Id": session_id,
        "Helicone-Session-Name": "Weather Assistant",
        "Helicone-Session-Path": "/weather/query"
    }
)

# Second message (same session)
response2 = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"},
        {"role": "assistant", "content": response1.choices[0].message.content},
        {"role": "user", "content": "What about tomorrow?"}
    ],
    extra_headers={
        "Helicone-Session-Id": session_id,
        "Helicone-Session-Name": "Weather Assistant",
        "Helicone-Session-Path": "/weather/followup"
    }
)

Multi-Step Workflow Example

Track complex workflows across multiple steps:

const sessionId = randomUUID();
const sessionName = "Travel Planner";

// Step 1: Search flights
await client.chat.completions.create(
  {
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Find flights to Tokyo' }]
  },
  {
    headers: {
      'Helicone-Session-Id': sessionId,
      'Helicone-Session-Name': sessionName,
      'Helicone-Session-Path': '/booking/flight/search'
    }
  }
);

// Step 2: Select flight
await client.chat.completions.create(
  {
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Book the 2pm flight' }]
  },
  {
    headers: {
      'Helicone-Session-Id': sessionId,
      'Helicone-Session-Name': sessionName,
      'Helicone-Session-Path': '/booking/flight/selection'
    }
  }
);

// Step 3: Confirm booking
await client.chat.completions.create(
  {
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Confirm the booking' }]
  },
  {
    headers: {
      'Helicone-Session-Id': sessionId,
      'Helicone-Session-Name': sessionName,
      'Helicone-Session-Path': '/booking/flight/confirm'
    }
  }
);

Viewing Sessions

Access your sessions in the dashboard:

1. Navigate to Sessions

   Go to the Sessions page in your Helicone dashboard

2. View Session List

   See all sessions with metrics: total cost, request count, duration, success rate

3. Click a Session

   View all requests in the session, organized by path/timestamp

4. Analyze Patterns

   Identify common flows, drop-off points, and expensive operations

Session Analytics

Helicone provides rich analytics for sessions:

Aggregate Metrics

• Total Cost: Sum of all request costs in the session
• Request Count: Number of requests in the session
• Duration: Time from first to last request
• Average Latency: Mean latency across all requests
• Success Rate: Percentage of successful requests

Per-Session Metrics

// Query session metrics via API
const response = await fetch('https://api.helicone.ai/v1/session/metrics/query', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    nameContains: "Travel Planner",
    timezoneDifference: 0,
    timeFilter: {
      startTimeUnixMs: Date.now() - 7 * 24 * 60 * 60 * 1000,
      endTimeUnixMs: Date.now()
    }
  })
});

const data = await response.json();
// Returns: total cost, count, avg latency, etc.

Session API

Query Sessions

Fetch sessions with filters and metrics

Session Metrics

Get aggregate metrics for sessions

Best Practices

Generate Unique Session IDs

Use UUIDs or unique identifiers for session IDs. Don’t reuse session IDs across different conversations.

import uuid
session_id = str(uuid.uuid4())

Use Descriptive Session Names

Give sessions meaningful names that describe the workflow or conversation type:

• Good: “Customer Support Chat”, “Recipe Generator”
• Bad: “Session 1”, “Test”

Track Session Paths

Use paths to track progress through multi-step workflows:

/onboarding/step1
/onboarding/step2
/onboarding/step3

Combine with User IDs

Track both session and user to understand per-user session patterns:

extra_headers={
    "Helicone-Session-Id": session_id,
    "Helicone-User-Id": user_id
}

Session Duration

Keep sessions focused on a single conversation or workflow. Start a new session for unrelated interactions.

Common Use Cases

Chatbots

Track complete conversations from greeting to resolution:

session_id = str(uuid.uuid4())
conversation = []

for user_message in chat_history:
    conversation.append({"role": "user", "content": user_message})
    
    response = client.chat.completions.create(
        model="gpt-4",
        messages=conversation,
        extra_headers={
            "Helicone-Session-Id": session_id,
            "Helicone-Session-Name": "Customer Support",
            "Helicone-Session-Path": f"/chat/message/{len(conversation)}"
        }
    )
    
    conversation.append({
        "role": "assistant",
        "content": response.choices[0].message.content
    })

Multi-Step Agents

Track agent workflows with multiple LLM calls:

session_id = str(uuid.uuid4())

# Step 1: Plan
plan = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": task}],
    extra_headers={
        "Helicone-Session-Id": session_id,
        "Helicone-Session-Path": "/agent/plan"
    }
)

# Step 2: Execute
result = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": f"Execute: {plan}"}],
    extra_headers={
        "Helicone-Session-Id": session_id,
        "Helicone-Session-Path": "/agent/execute"
    }
)

# Step 3: Reflect
reflection = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": f"Review: {result}"}],
    extra_headers={
        "Helicone-Session-Id": session_id,
        "Helicone-Session-Path": "/agent/reflect"
    }
)

User Onboarding

Track users through onboarding flows:

session_id = str(uuid.uuid4())

# Welcome
welcome = generate_welcome(user, session_id, "/onboarding/welcome")

# Collect preferences
prefs = collect_preferences(user, session_id, "/onboarding/preferences")

# Generate recommendations
recs = generate_recommendations(user, session_id, "/onboarding/recommendations")

# All tracked in the same session

Next Steps

Distributed Tracing

Track parent-child relationships between requests

Custom Properties

Add metadata to sessions

User Metrics

Combine sessions with user tracking

Request Logging

Learn about individual request logging