Skip to main content
Sessions let you group related LLM requests together to trace complete AI workflows. When building agents or chatbots that make multiple API calls to accomplish a task, sessions provide a unified view showing how all the pieces fit together.
Helicone session tracking interface showing hierarchical request structure

​
Why Use Sessions

Without sessions, you see individual requests in isolation:
  • ❌ Hard to trace which requests belong to the same workflow
  • ❌ Can’t measure total cost or latency for a task
  • ❌ Difficult to debug multi-step agent failures
  • ❌ No visibility into request dependencies
With sessions, you get complete workflow visibility:
  • ✅ Group all related requests under one session ID
  • ✅ Visualize parent-child relationships with path hierarchy
  • ✅ Calculate total cost, latency, and token usage per session
  • ✅ Debug agent workflows by tracing the entire execution flow

​
Quick Start

1

Add Session Headers

Include three required headers in your requests:
import { randomUUID } from "crypto";
import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://ai-gateway.helicone.ai",
  apiKey: process.env.HELICONE_API_KEY,
});

const sessionId = randomUUID();

await client.chat.completions.create(
  {
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Analyze this document..." }]
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/analyze",
      "Helicone-Session-Name": "Document Analyzer"
    }
  }
);
2

Structure Your Paths

Use path syntax to represent parent-child relationships:
// Parent request
"/analyze"                      // Top-level analysis

// Child requests
"/analyze/extract"             // Extract key information
"/analyze/summarize"           // Generate summary

// Grandchild requests
"/analyze/extract/validate"    // Validate extracted data
3

View in Dashboard

Visit helicone.ai/sessions to see your sessions:
  • View all sessions grouped by name
  • Click into a session to see the request hierarchy
  • Analyze session-level metrics (cost, duration, request count)
  • Filter by session name, date range, or properties

​
Session Components

​
Session ID

The unique identifier that groups requests together. Best Practices:
  • Use UUIDs for guaranteed uniqueness: randomUUID()
  • Generate a new ID for each workflow instance
  • Never reuse session IDs across different workflows
import { randomUUID } from "crypto";

// ✅ Good - unique ID per workflow
const sessionId = randomUUID();

// ❌ Bad - hardcoded ID reused across workflows
const sessionId = "my-session";

​
Session Path

Represents the hierarchical structure of your workflow. Path Rules:
  • Start with / (forward slash)
  • Use / to separate levels: /parent/child/grandchild
  • Group by function, not time
  • Same conceptual work = same path
Path Design Philosophy: Paths represent what the request does, not when it happens. Multiple requests can share the same path if they perform the same type of work. 
// ✅ Good - grouped by function
"/workflow"                    // Main workflow
"/workflow/research"           // Research phase
"/workflow/research/search"    // Web search (may happen multiple times)
"/workflow/analyze"            // Analysis phase
"/workflow/generate"           // Generation phase

// ❌ Bad - sequential numbering
"/step1"
"/step2" 
"/step3"
Why group by function? In the session timeline, requests with the same path are colored the same. This helps you:
  • Identify patterns (e.g., “all search operations are slow”)
  • See when different phases occur in the workflow
  • Compare durations across similar operations

​
Session Name

High-level grouping for filtering and organization. Best Practices:
  • Use descriptive names that describe the workflow type
  • Keep the same name across all requests in the session
  • Use session names to filter in the dashboard
// Good session names
"Customer Support Chat"
"Research Agent"
"Content Generator"
"Document Analyzer"
"Trip Planning Assistant"

// Use consistent names to group similar workflows
const sessionName = "Customer Support Chat"; // Same for all support sessions

​
Session Patterns

​
AI Agent Workflow

Track a multi-step agent that performs research and analysis: 
import { randomUUID } from "crypto";
import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://ai-gateway.helicone.ai",
  apiKey: process.env.HELICONE_API_KEY,
});

const sessionId = randomUUID();
const sessionName = "Research Agent";

// Step 1: Research phase
const research = await client.chat.completions.create(
  {
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Research the topic of quantum computing" }]
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/research",
      "Helicone-Session-Name": sessionName
    }
  }
);

// Step 2: Extract key facts
const facts = await client.chat.completions.create(
  {
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Extract key facts from this research: ..." }]
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/research/extract",
      "Helicone-Session-Name": sessionName
    }
  }
);

// Step 3: Analyze findings
const analysis = await client.chat.completions.create(
  {
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Analyze these facts: ..." }]
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/research/analyze",
      "Helicone-Session-Name": sessionName
    }
  }
);

// Step 4: Generate report
const report = await client.chat.completions.create(
  {
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Create a report from this analysis: ..." }]
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/research/analyze/report",
      "Helicone-Session-Name": sessionName
    }
  }
);

​
Multi-turn Chatbot

Track a conversation with multiple back-and-forth exchanges: 
const sessionId = randomUUID();
const sessionName = "Customer Support";

// User's first question
await client.chat.completions.create(
  {
    model: "gpt-4o-mini",
    messages: [
      { role: "system", content: "You are a helpful support agent." },
      { role: "user", content: "How do I reset my password?" }
    ]
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/question",
      "Helicone-Session-Name": sessionName,
      "Helicone-Property-Topic": "password_reset"
    }
  }
);

// User's follow-up question
await client.chat.completions.create(
  {
    model: "gpt-4o-mini",
    messages: [
      { role: "system", content: "You are a helpful support agent." },
      { role: "user", content: "How do I reset my password?" },
      { role: "assistant", content: "You can reset your password by..." },
      { role: "user", content: "I didn't receive the email" }
    ]
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/question",
      "Helicone-Session-Name": sessionName,
      "Helicone-Property-Topic": "password_reset"
    }
  }
);

​
Parallel Operations

Track multiple parallel operations in a workflow: 
const sessionId = randomUUID();
const sessionName = "Content Generator";

// Generate multiple variations in parallel
const variations = await Promise.all([
  client.chat.completions.create(
    { /* request */ },
    {
      headers: {
        "Helicone-Session-Id": sessionId,
        "Helicone-Session-Path": "/generate/variation",
        "Helicone-Session-Name": sessionName,
        "Helicone-Property-Variation": "A"
      }
    }
  ),
  client.chat.completions.create(
    { /* request */ },
    {
      headers: {
        "Helicone-Session-Id": sessionId,
        "Helicone-Session-Path": "/generate/variation",
        "Helicone-Session-Name": sessionName,
        "Helicone-Property-Variation": "B"
      }
    }
  ),
  client.chat.completions.create(
    { /* request */ },
    {
      headers: {
        "Helicone-Session-Id": sessionId,
        "Helicone-Session-Path": "/generate/variation",
        "Helicone-Session-Name": sessionName,
        "Helicone-Property-Variation": "C"
      }
    }
  )
]);

// Select best variation
await client.chat.completions.create(
  { /* request */ },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/generate/select",
      "Helicone-Session-Name": sessionName
    }
  }
);

​
Session Metrics

Helicone automatically calculates metrics for each session:
  • Total Cost: Sum of all request costs in the session
  • Duration: Time from first to last request
  • Request Count: Number of requests in the session
  • Total Tokens: Combined prompt and completion tokens
  • Average Latency: Mean latency across all requests
  • Status: Success if all requests succeeded, otherwise failed

​
Querying Sessions

Retrieve session data via the REST API:

​
Get All Sessions

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "search": "",
  "timeFilter": {
    "startTimeUnixMs": 1709222400000,
    "endTimeUnixMs": 1709308800000
  },
  "timezoneDifference": 0,
  "filter": "all",
  "limit": 100
}'

​
Filter by Session Name

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "search": "",
  "timeFilter": {
    "startTimeUnixMs": 1709222400000,
    "endTimeUnixMs": 1709308800000
  },
  "nameEquals": "Research Agent",
  "timezoneDifference": 0,
  "filter": "all",
  "limit": 100
}'

​
Get Session Metrics

curl --request POST \
  --url https://api.helicone.ai/v1/session/metrics/query \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "nameContains": "Research",
  "timezoneDifference": 0
}'

​
Combining with Custom Properties

Add custom properties to session requests for richer filtering: 
const sessionId = randomUUID();

await client.chat.completions.create(
  { /* request */ },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/research",
      "Helicone-Session-Name": "Research Agent",
      // Add custom properties
      "Helicone-Property-Environment": "production",
      "Helicone-Property-Topic": "quantum_computing",
      "Helicone-Property-Priority": "high",
      "Helicone-User-Id": "user-123"
    }
  }
);
Then filter sessions by these properties in the dashboard or API.

​
Best Practices

​
Session ID Management

✅ Do:
  • Generate a new UUID for each workflow instance
  • Store the session ID if you need to reference it later
  • Use the same session ID for all related requests
❌ Don’t:
  • Reuse session IDs across different workflows
  • Use predictable or sequential IDs
  • Change session IDs mid-workflow

​
Path Structure

✅ Do:
  • Keep paths concise and descriptive
  • Group by functionality, not by time
  • Use consistent naming conventions
  • Plan your hierarchy before implementing
❌ Don’t:
  • Use overly deep hierarchies (>5 levels)
  • Include timestamps or IDs in paths
  • Change path structure mid-session
  • Use special characters or spaces

​
Session Names

✅ Do:
  • Use descriptive, human-readable names
  • Keep the same name for similar workflows
  • Use names that make filtering easy
❌ Don’t:
  • Include IDs or timestamps in names
  • Use generic names like “Session” or “Request”
  • Change names mid-workflow

​
Troubleshooting

​
Requests Not Grouping

Problem: Requests aren’t appearing in the same session. Solutions:
  • Verify all requests use the exact same session ID
  • Check that session headers are included in every request
  • Ensure session ID is a string, not an object

​
Missing Session Hierarchy

Problem: Session shows requests but not the tree structure. Solutions:
  • Verify all requests have the Helicone-Session-Path header
  • Check that paths start with /
  • Ensure paths follow parent/child structure

​
Sessions Not Appearing in Dashboard

Problem: Sessions aren’t visible in the dashboard. Solutions:
  • Check that all three headers are included:
    • Helicone-Session-Id
    • Helicone-Session-Path
    • Helicone-Session-Name
  • Verify requests are successfully logged (check Requests page)
  • Wait a few seconds for data to propagate

Requests

View individual requests within your sessions

Custom Properties

Add metadata to session requests for filtering

Traces

Log non-LLM operations within your sessions

Session API

Query sessions programmatically via REST API

​
Questions?

Need help or have questions? We’re here to help:

Build docs developers (and LLMs) love

Get started for freeTalk to us