Session Tracking

What are Sessions?

Sessions allow you to group related LLM calls under a single identifier. This is useful for:

Multi-turn conversations - Track the entire conversation flow
User workflows - Analyze how users interact with your AI features
Debugging - Trace issues across multiple related calls
Analytics - Understand conversation patterns and user behavior

Use Cases

Chatbots

Group all messages in a conversation thread together

Multi-step Workflows

Track related API calls in complex workflows

A/B Testing

Compare conversation flows across different experiments

User Journeys

Analyze how users navigate your AI features

Vercel AI SDK

Pass session IDs via providerOptions.observ.sessionId:

import { generateText } from "ai";

// Group related calls with a session ID
const result = await generateText({
  model, // Your wrapped model
  prompt: "Explain React hooks",
  providerOptions: {
    observ: {
      sessionId: "conversation_abc123",
    },
  },
});

// All calls with the same sessionId will be grouped
// in your Observ dashboard for easy tracking

Provider SDKs

Chain .withSessionId() (TypeScript) or .with_session_id() (Python) before your API call.

Multi-turn Conversation Example

TypeScript
Python

// Group related calls with a session ID
const sessionId = "conversation_abc123";

// First message
const response1 = await wrappedClient.messages
  .withSessionId(sessionId)
  .create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    messages: [{ role: "user", content: "What is TypeScript?" }],
  });

// Follow-up in the same session
const response2 = await wrappedClient.messages
  .withSessionId(sessionId)
  .create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    messages: [
      { role: "user", content: "What is TypeScript?" },
      { role: "assistant", content: response1.content[0].text },
      { role: "user", content: "How does it compare to JavaScript?" },
    ],
  });

# Group related calls with a session ID
session_id = "conversation_abc123"

# First message
response1 = wrapped_client.messages.with_session_id(session_id).create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What is Python?"}],
)

# Follow-up in the same session
response2 = wrapped_client.messages.with_session_id(session_id).create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "What is Python?"},
        {"role": "assistant", "content": response1.content[0].text},
        {"role": "user", "content": "How does it compare to JavaScript?"},
    ],
)

All Providers

Sessions work with all supported providers:

TypeScript
Python

Anthropic

const response = await wrappedClient.messages
  .withSessionId("conversation_abc123")
  .create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello!" }],
  });

OpenAI

const response = await wrappedClient.chat.completions
  .withSessionId("conversation_abc123")
  .create({
    model: "gpt-4",
    messages: [{ role: "user", content: "Hello!" }],
  });

Mistral

const response = await wrappedClient.chat.completions
  .withSessionId("conversation_abc123")
  .create({
    model: "mistral-large-latest",
    messages: [{ role: "user", content: "Hello!" }],
  });

xAI

const response = await wrappedClient.chat.completions
  .withSessionId("conversation_abc123")
  .create({
    model: "grok-beta",
    messages: [{ role: "user", content: "Hello!" }],
  });

OpenRouter

const response = await wrappedClient.chat.completions
  .withSessionId("conversation_abc123")
  .create({
    model: "anthropic/claude-3.5-sonnet",
    messages: [{ role: "user", content: "Hello!" }],
  });

Anthropic

response = wrapped_client.messages.with_session_id("conversation_abc123").create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)

OpenAI

response = wrapped_client.chat.completions.with_session_id("conversation_abc123").create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}],
)

Mistral

response = wrapped_client.chat.completions.with_session_id("conversation_abc123").create(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Hello!"}],
)

Google (Gemini)

response = wrapped_model.with_session_id("conversation_abc123").generate_content(
    "Hello!"
)

xAI

response = wrapped_client.chat.completions.with_session_id("conversation_abc123").create(
    model="grok-beta",
    messages=[{"role": "user", "content": "Hello!"}],
)

OpenRouter

response = wrapped_client.chat.completions.with_session_id("conversation_abc123").create(
    model="anthropic/claude-3.5-sonnet",
    messages=[{"role": "user", "content": "Hello!"}],
)

Best Practices

Use consistent session IDs

Use the same session ID across all calls in a conversation thread. Generate unique IDs per conversation (e.g., UUIDs, user IDs + timestamp).

// Good - consistent ID per conversation
const sessionId = `user_${userId}_${timestamp}`;

// Bad - random ID per call
const sessionId = Math.random().toString();

Include context in session IDs

Make session IDs meaningful for easier debugging:

// Good - includes context
const sessionId = `support_chat_user123_20240108`;

// Bad - opaque ID
const sessionId = "abc123";

Clean up old sessions

Session IDs are just strings - they don’t consume resources. However, for privacy, you may want to rotate them periodically.

Viewing Sessions in Dashboard

All traces with the same session ID are grouped together in the Dashboard. You can:

View the entire conversation flow
See timing and cost for each call
Filter by session ID
Analyze conversation patterns

Use consistent session IDs for conversation threads. View grouped traces in the Dashboard.

Next Steps

Custom Metadata

Attach metadata to your traces

Provider SDKs

Learn about provider SDK integration

Vercel AI SDK

Learn about Vercel AI SDK integration

Dashboard

View your traces and analytics

Getting Started

Usage

Features

Session Tracking

What are Sessions?

Use Cases

Chatbots

Multi-step Workflows

A/B Testing

User Journeys

Vercel AI SDK

Provider SDKs

Multi-turn Conversation Example

All Providers

Best Practices

Viewing Sessions in Dashboard

Next Steps

Custom Metadata

Provider SDKs

Vercel AI SDK

Dashboard

​What are Sessions?

​Use Cases

Chatbots

Multi-step Workflows

A/B Testing

User Journeys

​Vercel AI SDK

​Provider SDKs

​Multi-turn Conversation Example

​All Providers

​Best Practices

​Viewing Sessions in Dashboard

​Next Steps

Custom Metadata

Provider SDKs

Vercel AI SDK

Dashboard

What are Sessions?

Use Cases

Vercel AI SDK

Provider SDKs

Multi-turn Conversation Example

All Providers

Best Practices

Viewing Sessions in Dashboard

Next Steps