KnowledgeMay 8, 2026·4 min read

Helicone Sessions — Group LLM Calls by User Conversation

Helicone Sessions group multiple LLM calls under one session ID. Trace a multi-step agent run end-to-end, see total cost, latency, conversation flow.

Helicone
Helicone · Community
Agent ready

Review-first install path

This asset needs a review step. The copied prompt tells the agent to dry-run, show the writes, then proceed only after confirmation.

Needs Confirmation · 64/100Policy: confirm
Agent surface
Any MCP/CLI agent
Kind
Knowledge
Install
Single
Trust
Trust: Community
Entrypoint
Asset
Review-first command
npx -y tokrepo@latest install f7a06a3c-8989-4b10-85d5-df805477ec74 --target codex

Dry-run first, confirm the writes, then run this command.

Intro

Helicone Sessions group LLM calls that belong to the same user conversation, agent run, or workflow under one session ID. Trace a multi-step agent end-to-end, see total cost / latency / token usage, and visualize the conversation as a tree. Best for: multi-turn agents, RAG pipelines with intermediate calls, anywhere you'd otherwise lose the context of which call belonged to which run. Works with: Helicone Cloud + self-hosted, any OpenAI / Anthropic SDK. Setup time: 2 minutes.

Tag a session

from openai import OpenAI

client = OpenAI(
    base_url="https://oai.helicone.ai/v1",
    default_headers={
        "Helicone-Auth": f"Bearer {HELICONE_KEY}",
        "Helicone-Session-Id": "session_abc123",
        "Helicone-Session-Name": "support_ticket_4521",
        "Helicone-Session-Path": "/triage/research/respond",
    },
)

# Each call inside this session is grouped together
client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Help me triage ticket #4521"}],
)

Multiple calls with the same Helicone-Session-Id aggregate in the dashboard.

Path-based hierarchy

# Top-level: triage
client.chat.completions.create(
    extra_headers={"Helicone-Session-Path": "/triage"},
    ...
)

# Sub-step: classify intent
client.chat.completions.create(
    extra_headers={"Helicone-Session-Path": "/triage/classify"},
    ...
)

# Sub-step: generate response
client.chat.completions.create(
    extra_headers={"Helicone-Session-Path": "/triage/respond"},
    ...
)

The dashboard renders the path as a tree, so you see the agent's decision flow.

Why use Sessions vs raw logs

Without Sessions With Sessions
100 calls per agent run, hard to attribute One session = one run, all calls grouped
No total cost per workflow Total cost / latency / tokens per session
Find issues by call ID Find issues by run ID, see all related calls
Can't replay a multi-step flow Replay the entire session tree

FAQ

Q: Is Helicone Sessions free? A: Yes — Sessions are part of the Helicone free tier (10K requests/month). Paid plans add longer retention and higher quotas. Self-hosted Helicone supports Sessions natively.

Q: Do I need to change my SDK? A: No — Helicone is a proxy. Switch your OpenAI / Anthropic / etc base URL to Helicone's, add the Helicone-Auth header. Sessions are opt-in via additional headers.

Q: Can I use Sessions with Anthropic Claude? A: Yes — Helicone proxies Anthropic, OpenAI, Google, Bedrock, OpenRouter. Set base URL to https://anthropic.helicone.ai, pass the same Helicone-Session-* headers.

Quick Use

  1. Sign up at helicone.ai → copy API key
  2. Switch your LLM SDK base_url to https://oai.helicone.ai/v1 (or anthropic.helicone.ai etc)
  3. Add Helicone-Session-Id header — every matching call is grouped

Intro

Helicone Sessions group LLM calls that belong to the same user conversation, agent run, or workflow under one session ID. Trace a multi-step agent end-to-end, see total cost / latency / token usage, and visualize the conversation as a tree. Best for: multi-turn agents, RAG pipelines with intermediate calls, anywhere you'd otherwise lose the context of which call belonged to which run. Works with: Helicone Cloud + self-hosted, any OpenAI / Anthropic SDK. Setup time: 2 minutes.

Tag a session

from openai import OpenAI

client = OpenAI(
    base_url="https://oai.helicone.ai/v1",
    default_headers={
        "Helicone-Auth": f"Bearer {HELICONE_KEY}",
        "Helicone-Session-Id": "session_abc123",
        "Helicone-Session-Name": "support_ticket_4521",
        "Helicone-Session-Path": "/triage/research/respond",
    },
)

# Each call inside this session is grouped together
client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Help me triage ticket #4521"}],
)

Multiple calls with the same Helicone-Session-Id aggregate in the dashboard.

Path-based hierarchy

# Top-level: triage
client.chat.completions.create(
    extra_headers={"Helicone-Session-Path": "/triage"},
    ...
)

# Sub-step: classify intent
client.chat.completions.create(
    extra_headers={"Helicone-Session-Path": "/triage/classify"},
    ...
)

# Sub-step: generate response
client.chat.completions.create(
    extra_headers={"Helicone-Session-Path": "/triage/respond"},
    ...
)

The dashboard renders the path as a tree, so you see the agent's decision flow.

Why use Sessions vs raw logs

Without Sessions With Sessions
100 calls per agent run, hard to attribute One session = one run, all calls grouped
No total cost per workflow Total cost / latency / tokens per session
Find issues by call ID Find issues by run ID, see all related calls
Can't replay a multi-step flow Replay the entire session tree

FAQ

Q: Is Helicone Sessions free? A: Yes — Sessions are part of the Helicone free tier (10K requests/month). Paid plans add longer retention and higher quotas. Self-hosted Helicone supports Sessions natively.

Q: Do I need to change my SDK? A: No — Helicone is a proxy. Switch your OpenAI / Anthropic / etc base URL to Helicone's, add the Helicone-Auth header. Sessions are opt-in via additional headers.

Q: Can I use Sessions with Anthropic Claude? A: Yes — Helicone proxies Anthropic, OpenAI, Google, Bedrock, OpenRouter. Set base URL to https://anthropic.helicone.ai, pass the same Helicone-Session-* headers.

Source & Thanks

Built by Helicone. Licensed under Apache-2.0.

Helicone/helicone — ⭐ 4,000+

🙏

Source & Thanks

Built by Helicone. Licensed under Apache-2.0.

Helicone/helicone — ⭐ 4,000+

Discussion

Sign in to join the discussion.
No comments yet. Be the first to share your thoughts.

Related Assets

Helicone Cache — Cut LLM Spend with Drop-In Response Caching

Helicone Cache short-circuits identical LLM requests at the proxy. Set Helicone-Cache-Enabled header, exact-match responses come back in ms at zero cost.

Knowledge
Helicone

LLM Prompt Caching — Cache-Key Design Runbook

LLM prompt caching techniques for agents and apps. Covers stable prefixes, cache keys, TTLs, metrics, and cached-output validation.

Knowledge
henuwangkai

Mem0 — Memory Layer for AI Applications

Add persistent, personalized memory to AI agents and assistants. Mem0 stores user preferences, past interactions, and learned context across sessions.

Knowledge
Mem0

free-ai-tools — Curated List of Practical AI Developer Tools

A curated list of free/low-cost AI developer tools (LLM APIs, IDEs, agents, infra) for quickly building real apps. Verified 284★; pushed 2026-05-14.

Knowledge
AI Open Source
◈Home🔍Search👤Me