Sessions

When building AI agents or complex workflows, your application often makes multiple LLM calls, vector database queries, and tool calls to complete a single task. Sessions group these related requests together, letting you trace the entire agent flow from initial user input to final response in one unified view.

Why use Sessions

• Debug AI agent flows: See the entire agent workflow in one view, from initial request to final response
• Track multi-step conversations: Reconstruct the complete flow of chatbot interactions and complex tasks
• Analyze performance: Measure outcomes across entire interaction sequences, not just individual requests

Quick Start

1. Add Session Headers

   Include three required headers in your LLM requests:

   {
     "Helicone-Session-Id": "unique-session-id",
     "Helicone-Session-Path": "/trace-path", 
     "Helicone-Session-Name": "Session Name"
   }
   
2. Structure Your Paths

   Use path syntax to represent parent-child relationships:

   "/abstract"                    // Top-level trace
   "/abstract/outline"           // Child trace
   "/abstract/outline/lesson-1"  // Grandchild trace
   
3. Make Your Request

   Execute your LLM request with the session headers included:

   const response = await client.chat.completions.create(
     { 
       messages: [{ role: "user", content: "Hello" }], 
       model: "gpt-4o-mini" 
     },
     {
       headers: {
         "Helicone-Session-Id": sessionId,
         "Helicone-Session-Path": "/greeting",
         "Helicone-Session-Name": "User Conversation"
       }
     }
   );
   

Understanding Sessions

What Sessions Can Track

Sessions can group together all types of requests in your AI workflow:

• LLM calls - OpenAI, Anthropic, and other model requests
• Vector database queries - Embeddings, similarity searches, and retrievals
• Tool calls - Function executions, API calls, and custom tools
• Any logged request - Anything sent through Helicone’s logging

This gives you a complete view of your AI agent’s behavior, not just the LLM interactions.

Session IDs

The session ID is a unique identifier that groups all related requests together. Think of it as a conversation thread ID.

What to use:

• UUIDs (recommended): 550e8400-e29b-41d4-a716-446655440000
• Unique strings: user_123_conversation_456

Why it matters:

• Same ID = requests get grouped together in the dashboard
• Different IDs = separate sessions, even if they’re related
• Reusing IDs across different workflows will mix unrelated requests

// ✅ Good - unique per conversation
const sessionId = randomUUID(); // Different for each user conversation

// ❌ Bad - reuses same ID
const sessionId = "chat_session"; // All users get mixed together

Session Paths

Paths create the hierarchy within your session, showing how requests relate to each other.

Path Naming Philosophy:

Think of session paths as conceptual groupings rather than chronological order. Requests with the same path represent the same “type” of work, even if they happen at different times.

Example: In a code review agent, all “security check” requests get the same path (/review/security) whether they happen early or late in the analysis. This lets you see patterns in the duration distribution chart - all security checks will be colored the same, showing you when they typically occur and how long they take.

Path Structure Rules:

• Start with / (forward slash)
• Use / to separate levels: /parent/child/grandchild
• Keep names descriptive: /analyze_request/fetch_data/process_results
• Group by function, not by time - same conceptual work = same path

How Hierarchy Works:

"/conversation"                    // Root level
"/conversation/initial_question"   // Child of conversation  
"/conversation/followup"          // Another child of conversation
"/conversation/followup/clarify"  // Child of followup

Path Design Patterns:

// Workflow pattern - good for AI agents
"/task"
"/task/research" 
"/task/research/web_search"
"/task/generate"

// Conversation pattern - good for chatbots
"/session"
"/session/question_1"
"/session/answer_1" 
"/session/question_2"

// Pipeline pattern - good for data processing
"/process"
"/process/extract"
"/process/transform"
"/process/load"

Session Names

The session name is a high-level grouping that makes it easy to filter and organize similar types of sessions in the dashboard.

Good session names:

• "Customer Support" - All support sessions use this name
• "Content Generation" - All content creation sessions use this name
• "Trip Planning Agent" - All trip planning workflows use this name

Purpose:

• Quick filtering - Filter dashboard to show only “Customer Support” sessions
• High-level organization - Group alike sessions for easy comparison
• Performance analysis - Compare metrics across the same session type

Configuration Reference

Required Headers

Helicone-Session-Id · string · required

Unique identifier for the session. Use UUIDs to avoid conflicts.

Example: "550e8400-e29b-41d4-a716-446655440000"

Helicone-Session-Path · string · required

Path representing the trace hierarchy using / syntax. Shows parent-child relationships.

Example: "/abstract" or "/parent/child"

Helicone-Session-Name · string · required

Human-readable name for the session type. Groups similar workflows together.

Example: "Course Plan" or "Customer Support"

Common Patterns

Code Generation Assistant

Track a complete code generation workflow with clarifications and refinements:

Node.js

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();

// Initial feature request
const response1 = await client.chat.completions.create(
  {
    messages: [{ role: "user", content: "Create a React component for user authentication with email and password" }],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/request",
      "Helicone-Session-Name": "Code Generation Assistant",
    },
  }
);

// User asks for clarification
const response2 = await client.chat.completions.create(
  {
    messages: [
      { role: "user", content: "Create a React component for user authentication with email and password" },
      { role: "assistant", content: response1.choices[0].message.content },
      { role: "user", content: "Can you add form validation and error handling?" }
    ],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/request/validation",
      "Helicone-Session-Name": "Code Generation Assistant",
    },
  }
);

// User requests TypeScript version
const response3 = await client.chat.completions.create(
  {
    messages: [
      { role: "user", content: "Convert this to TypeScript with proper interfaces" }
    ],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/request/validation/typescript",
      "Helicone-Session-Name": "Code Generation Assistant",
    },
  }
);

Pull Request Review

Track an automated PR review workflow with multiple analysis steps:

const sessionId = randomUUID();

// Initial PR analysis
const analysis = await client.chat.completions.create(
  { 
    messages: [{ role: "user", content: "Analyze this pull request for code quality and potential issues: [PR diff content]" }],
    model: "gpt-4o-mini" 
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/analysis",
      "Helicone-Session-Name": "PR Review Bot",
    },
  }
);

// Security check
const securityCheck = await client.chat.completions.create(
  { 
    messages: [{ role: "user", content: "Check for security vulnerabilities: SQL injection, XSS, authentication issues" }],
    model: "gpt-4o-mini" 
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/analysis/security",
      "Helicone-Session-Name": "PR Review Bot",
    },
  }
);

// Generate review comments
const reviewComments = await client.chat.completions.create(
  { 
    messages: [{ role: "user", content: "Generate constructive review comments based on analysis" }],
    model: "gpt-4o-mini" 
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/analysis/security/comments",
      "Helicone-Session-Name": "PR Review Bot",
    },
  }
);

API Documentation Generator

Track a multi-step API documentation generation workflow:

const sessionId = randomUUID();

// Analyze API endpoints
const endpoints = await client.chat.completions.create(
  {
    messages: [{ role: "user", content: "Analyze these API routes and extract endpoint information: [code content]" }],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/analyze",
      "Helicone-Session-Name": "API Documentation Generator",
    },
  }
);

// Generate OpenAPI spec
const openApiSpec = await client.chat.completions.create(
  {
    messages: [
      { role: "user", content: "Generate OpenAPI 3.0 specification based on these endpoints" }
    ],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/analyze/openapi",
      "Helicone-Session-Name": "API Documentation Generator",
    },
  }
);

// Create usage examples
const examples = await client.chat.completions.create(
  {
    messages: [{ role: "user", content: "Create code examples for each endpoint in multiple languages" }],
    model: "gpt-4o-mini",
  },
  {
    headers: {
      "Helicone-Session-Id": sessionId,
      "Helicone-Session-Path": "/analyze/openapi/examples",
      "Helicone-Session-Name": "API Documentation Generator",
    },
  }
);

Complete Session Example

Full JavaScript implementation showing session hierarchy and tracking

Querying Sessions via API

Once you’ve created sessions, you can query and filter them using the Session Query API. This is essential for debugging, analytics, and building custom dashboards.

Basic Session Query

Query all sessions within a time range:

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "limit": 100
}'

Time Parameters:

• startTimeUnixMs and endTimeUnixMs are Unix timestamps in milliseconds
• timezoneDifference is the offset in hours (e.g., -5 for EST, 0 for UTC)
• All three parameters are required

Filter by Session Name

Find all sessions of a specific type:

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "nameEquals": "Customer Support",
  "limit": 100
}'

Filter by Custom Properties

Query sessions with specific custom properties (e.g., product type and source):

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "filter": {
    "left": {
      "session": {
        "properties": {
          "product": {
            "equals": "ai-writer"
          }
        }
      }
    },
    "operator": "and",
    "right": {
      "session": {
        "properties": {
          "source": {
            "equals": "slack"
          }
        }
      }
    }
  },
  "limit": 100
}'

Important: When filtering by custom properties in sessions, wrap the properties filter inside a session object. Each property condition must be a separate leaf node connected with and/or operators.

Combine Multiple Filters

Query sessions by name AND custom properties:

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "nameEquals": "Code Generation Assistant",
  "filter": {
    "session": {
      "properties": {
        "environment": {
          "equals": "production"
        }
      }
    }
  },
  "limit": 100
}'

Common Query Patterns

Last 24 Hours by User

Find all sessions from a specific user in the last 24 hours:

# Calculate timestamps (example for last 24 hours)
END_TIME=$(date +%s)000  # Current time in milliseconds
START_TIME=$((END_TIME - 86400000))  # 24 hours ago

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data "{
  \"startTimeUnixMs\": $START_TIME,
  \"endTimeUnixMs\": $END_TIME,
  \"timezoneDifference\": 0,
  \"filter\": {
    \"session\": {
      \"properties\": {
        \"user-id\": {
          \"equals\": \"user-123\"
        }
      }
    }
  },
  \"limit\": 100
}"

Debug Failed Sessions

Find sessions with error status:

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "filter": {
    "session": {
      "properties": {
        "status": {
          "equals": "error"
        }
      }
    }
  },
  "limit": 100
}'

Search by Keyword

Search sessions by name or metadata:

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "search": "authentication",
  "limit": 100
}'

Production Sessions Only

Filter by environment and date range:

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "filter": {
    "left": {
      "session": {
        "properties": {
          "environment": {
            "equals": "production"
          }
        }
      }
    },
    "operator": "and",
    "right": {
      "session": {
        "properties": {
          "version": {
            "equals": "v2.1.0"
          }
        }
      }
    }
  },
  "limit": 100
}'

Pagination

Use offset and limit to paginate through results:

# First page (0-99)
curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "offset": 0,
  "limit": 100
}'

# Second page (100-199)
curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "offset": 100,
  "limit": 100
}'

Getting Requests Within a Session

Once you have a session, retrieve all its requests using the Request Query API:

curl --request POST \
  --url https://api.helicone.ai/v1/request/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "filter": {
    "properties": {
      "Helicone-Session-Id": {
        "equals": "your-session-id-here"
      }
    }
  }
}'

For detailed information on querying requests, see the Request Query API documentation.

Related Features

Session Query API

Complete API reference for querying sessions

Vector Database Logging

Track vector database queries and embeddings alongside LLM calls

Tool Call Logging

Monitor tool calls and function executions within your agent workflows

Custom Properties

Add metadata to individual requests within sessions

User Metrics

Track user behavior patterns across multiple sessions

---

Need more help?

Additional questions or feedback? Reach out to [e-mail] or schedule a call with us.