> ## Documentation Index
> Fetch the complete documentation index at: https://docs.observ.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Tracking

> Group related LLM calls together using session IDs - perfect for tracking multi-turn conversations and analyzing user workflows

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

<CardGroup cols={2}>
  <Card title="Chatbots" icon="message-square">
    Group all messages in a conversation thread together
  </Card>

  <Card title="Multi-step Workflows" icon="workflow">
    Track related API calls in complex workflows
  </Card>

  <Card title="A/B Testing" icon="flask">
    Compare conversation flows across different experiments
  </Card>

  <Card title="User Journeys" icon="route">
    Analyze how users navigate your AI features
  </Card>
</CardGroup>

## Vercel AI SDK

Pass session IDs via `providerOptions.observ.sessionId`:

```typescript theme={null}
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

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    // 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?" },
        ],
      });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # 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?"},
        ],
    )
    ```
  </Tab>
</Tabs>

### All Providers

Sessions work with all supported providers:

<Tabs>
  <Tab title="TypeScript">
    <AccordionGroup>
      <Accordion title="Anthropic">
        ```typescript theme={null}
        const response = await wrappedClient.messages
          .withSessionId("conversation_abc123")
          .create({
            model: "claude-sonnet-4-20250514",
            max_tokens: 1024,
            messages: [{ role: "user", content: "Hello!" }],
          });
        ```
      </Accordion>

      <Accordion title="OpenAI">
        ```typescript theme={null}
        const response = await wrappedClient.chat.completions
          .withSessionId("conversation_abc123")
          .create({
            model: "gpt-4",
            messages: [{ role: "user", content: "Hello!" }],
          });
        ```
      </Accordion>

      <Accordion title="Mistral">
        ```typescript theme={null}
        const response = await wrappedClient.chat.completions
          .withSessionId("conversation_abc123")
          .create({
            model: "mistral-large-latest",
            messages: [{ role: "user", content: "Hello!" }],
          });
        ```
      </Accordion>

      <Accordion title="xAI">
        ```typescript theme={null}
        const response = await wrappedClient.chat.completions
          .withSessionId("conversation_abc123")
          .create({
            model: "grok-beta",
            messages: [{ role: "user", content: "Hello!" }],
          });
        ```
      </Accordion>

      <Accordion title="OpenRouter">
        ```typescript theme={null}
        const response = await wrappedClient.chat.completions
          .withSessionId("conversation_abc123")
          .create({
            model: "anthropic/claude-3.5-sonnet",
            messages: [{ role: "user", content: "Hello!" }],
          });
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Python">
    <AccordionGroup>
      <Accordion title="Anthropic">
        ```python theme={null}
        response = wrapped_client.messages.with_session_id("conversation_abc123").create(
            model="claude-sonnet-4-20250514",
            max_tokens=1024,
            messages=[{"role": "user", "content": "Hello!"}],
        )
        ```
      </Accordion>

      <Accordion title="OpenAI">
        ```python theme={null}
        response = wrapped_client.chat.completions.with_session_id("conversation_abc123").create(
            model="gpt-4",
            messages=[{"role": "user", "content": "Hello!"}],
        )
        ```
      </Accordion>

      <Accordion title="Mistral">
        ```python theme={null}
        response = wrapped_client.chat.completions.with_session_id("conversation_abc123").create(
            model="mistral-large-latest",
            messages=[{"role": "user", "content": "Hello!"}],
        )
        ```
      </Accordion>

      <Accordion title="Google (Gemini)">
        ```python theme={null}
        response = wrapped_model.with_session_id("conversation_abc123").generate_content(
            "Hello!"
        )
        ```
      </Accordion>

      <Accordion title="xAI">
        ```python theme={null}
        response = wrapped_client.chat.completions.with_session_id("conversation_abc123").create(
            model="grok-beta",
            messages=[{"role": "user", "content": "Hello!"}],
        )
        ```
      </Accordion>

      <Accordion title="OpenRouter">
        ```python theme={null}
        response = wrapped_client.chat.completions.with_session_id("conversation_abc123").create(
            model="anthropic/claude-3.5-sonnet",
            messages=[{"role": "user", "content": "Hello!"}],
        )
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## Best Practices

<AccordionGroup>
  <Accordion title="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).

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

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

  <Accordion title="Include context in session IDs">
    Make session IDs meaningful for easier debugging:

    ```typescript theme={null}
    // Good - includes context
    const sessionId = `support_chat_user123_20240108`;

    // Bad - opaque ID
    const sessionId = "abc123";
    ```
  </Accordion>

  <Accordion title="Clean up old sessions">
    Session IDs are just strings - they don't consume resources. However, for privacy, you may want to rotate them periodically.
  </Accordion>
</AccordionGroup>

## Viewing Sessions in Dashboard

All traces with the same session ID are grouped together in the [Dashboard](https://observ.dev/dashboard).

You can:

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

<Tip>
  Use consistent session IDs for conversation threads. View grouped traces in
  the [Dashboard](https://observ.dev/dashboard).
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Custom Metadata" icon="tag" href="/features/metadata">
    Attach metadata to your traces
  </Card>

  <Card title="Provider SDKs" icon="code" href="/provider-sdks/overview">
    Learn about provider SDK integration
  </Card>

  <Card title="Vercel AI SDK" icon="zap" href="/vercel-ai/overview">
    Learn about Vercel AI SDK integration
  </Card>

  <Card title="Dashboard" icon="gauge" href="https://observ.dev/dashboard">
    View your traces and analytics
  </Card>
</CardGroup>