# 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.

## Install

Copy the content below into your project:

## 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

```python
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

```python
# 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](https://github.com/Helicone). Licensed under Apache-2.0.
>
> [Helicone/helicone](https://github.com/Helicone/helicone) — ⭐ 4,000+

---

<!-- ZH -->

## 快速使用

1. 在 helicone.ai 注册，复制 API key
2. 把 LLM SDK 的 base_url 切到 `https://oai.helicone.ai/v1`（或 anthropic.helicone.ai 等）
3. 加 `Helicone-Session-Id` header，所有相同 ID 的调用自动分组

---

## 简介

Helicone Sessions 把同一个用户对话、agent 运行、工作流下的多次 LLM 调用归到一个 session ID。端到端追踪多步 agent、看总成本/延迟/token 用量、把对话可视化成树。适合多轮 agent、带中间调用的 RAG 流水线、任何会丢失「哪次调用属于哪次运行」上下文的场景。兼容 Helicone Cloud + 自托管、任何 OpenAI / Anthropic SDK。装机时间 2 分钟。

---

### 给 session 打标

```python
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",
    },
)

# 这个 session 内所有调用被分组
client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Help me triage ticket #4521"}],
)
```

同一 `Helicone-Session-Id` 的多次调用在仪表盘聚合。

### 路径层级

```python
# 顶层：triage
client.chat.completions.create(
    extra_headers={"Helicone-Session-Path": "/triage"},
    ...
)

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

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

仪表盘把路径渲染成树，能看 agent 的决策流。

### Session vs 裸日志

| 没 Session | 有 Session |
|---|---|
| 一次 agent 跑 100 次调用，难归属 | 一个 session = 一次跑，所有调用分组 |
| 没有 workflow 总成本 | session 维度的成本/延迟/token |
| 按 call ID 找问题 | 按 run ID 找问题，看所有相关调用 |
| 没法回放多步流程 | 回放整个 session 树 |

---

### FAQ

**Q: Helicone Sessions 免费吗？**
A: 免费 —— Session 包含在 Helicone 免费档（每月 10K 请求）。付费档加更长保留期和更高配额。自托管 Helicone 原生支持 Session。

**Q: 要改 SDK 吗？**
A: 不用 —— Helicone 是 proxy。把 OpenAI / Anthropic 等的 base URL 切到 Helicone，加 Helicone-Auth header。Session 是 opt-in，加额外 header 启用。

**Q: 能配 Anthropic Claude 吗？**
A: 能 —— Helicone 代理 Anthropic / OpenAI / Google / Bedrock / OpenRouter。base URL 设 `https://anthropic.helicone.ai`，传同样的 Helicone-Session-* header。

---

## 来源与感谢

> Built by [Helicone](https://github.com/Helicone). Licensed under Apache-2.0.
>
> [Helicone/helicone](https://github.com/Helicone/helicone) — ⭐ 4,000+


---
Source: https://tokrepo.com/en/workflows/helicone-sessions-group-llm-calls-by-user-conversation
Author: Helicone