A session groups all LLM calls from a single user conversation into a single unit of analysis. Where the Traces view shows individual LLM API calls, the Sessions view shows full conversations — how many turns they had, how much they cost in total, and how long they lasted from first to last message.
Setting up session tracking
To use the Sessions view, pass a sessionId when initializing your trace context. The session ID should be stable for the duration of a conversation — typically a UUID you generate when the conversation starts.
import { zespan, withLumiqtraceContext } from "@zespan/sdk";
import OpenAI from "openai";
zespan.init({ apiKey: process.env.ZESPAN_API_KEY! });
const openai = zespan.wrapOpenAI(new OpenAI());
// Generate once per conversation
const sessionId = crypto.randomUUID();
async function handleMessage(userId: string, message: string) {
return withLumiqtraceContext(
{ userId, sessionId },
async () => {
const response = await openai.chat.completions.create({
model: "gpt-4o",
messages: [{ role: "user", content: message }],
});
return response.choices[0].message.content;
}
);
}
import zespan
from zespan import with_zespan_context
import uuid
zespan.init(api_key="zsp_your_api_key_here")
zespan.patch_openai()
import openai
client = openai.OpenAI()
session_id = str(uuid.uuid4()) # Generated once per conversation
def handle_message(user_id: str, message: str) -> str:
with with_zespan_context(user_id=user_id, session_id=session_id):
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": message}],
)
return response.choices[0].message.content
sessionId are linked together in the Sessions view, regardless of which trace they belong to.
The sessions list
The Sessions page shows a paginated table of all sessions in your project:
| Column | Description |
|---|
| Session ID | The identifier you provided |
| User ID | The user associated with the session (if set) |
| Started | When the first LLM call in this session was made |
| Duration | Time from first to last call |
| Turns | Number of LLM calls in the session |
| Cost | Total cost across all calls in the session |
| Status | Whether the session ended with any errors |
Filtering sessions
Use the filter bar to narrow the list by:
- Date range — see sessions from a specific period
- User ID — view all sessions for a specific user
- Status — filter to sessions with errors
- Minimum turns — find longer conversations
Session detail
Click any session row to open its detail view. The detail view shows:
Conversation timeline
A sequential list of every LLM call in the session, in chronological order. Each entry shows the model, latency, token count, and cost for that call. Click any entry to open the full trace flame graph.
Session metrics
- Total cost — cumulative spend across all calls
- Total tokens — combined input and output tokens
- Average latency per turn — mean response time across all calls
- Error count — number of calls that ended in an error state
User attribution
If the session was associated with a userId, the user’s full session history is available from a link at the top of the detail view. This lets you see all sessions for a user in one place — useful for investigating a user complaint or analysing high-value customers.
Cost attribution by session
In addition to per-model cost breakdown, the Sessions view helps answer questions like:
- “Which types of conversations cost the most?”
- “Are there sessions where users are burning through tokens disproportionately?”
- “What is my average cost per conversation?”
Sort sessions by cost and examine the top 10 most expensive sessions. If they share a common pattern — a specific feature, user segment, or prompt style — that’s where to focus optimization effort first.
Plan requirements
Session tracking is available on all plans. The Sessions page is populated automatically as long as your SDK passes sessionId in its trace context. No additional configuration is required.
Data retention for session data follows your plan’s retention window — 14 days on Free, 30 days on Solo, 90 days on Pro, 180 days on Team, 1 year on Scale. 
