Link session replay

Connecting your backend LLM events to frontend session replays provides complete visibility into the user journey, helping you understand the full context around AI interactions in your application.

Why link to session replay?

By including session IDs in your LLM events, you can:

• See the full user journey: Navigate from an LLM trace directly to the session replay to see user actions before, during, and after AI interactions
• Debug issues faster: Quickly find and watch the exact session where problems occurred
• Understand user behavior: See how users interact with AI features and what prompts they use
• Correlate performance: Match slow AI responses with actual user experience impact

Implementation

There are two ways to pass session IDs from your frontend to your backend:

1. Automatic header injection - posthog-js automatically adds headers to your API requests
2. Manual approach - explicitly pass the session ID in your request body

Option 1: Automatic header injection (recommended)

Configure posthog-js to automatically inject session headers into requests to your backend:

posthog.init('<ph_project_api_key>', {
  api_host: 'https://us.i.posthog.com',
  __add_tracing_headers: ['api.your-app.com']  // Your backend hostname(s)
})

This automatically adds X-POSTHOG-SESSION-ID (and X-POSTHOG-DISTINCT-ID) headers to all fetch and XMLHttpRequest calls to the specified hostnames.

On your backend, read the header and include it in your LLM tracking:

app.post('/api/chat', async (req, res) => {
  const sessionId = req.headers['x-posthog-session-id']

  const response = await openai.responses.create({
    model: 'gpt-5',
    messages: [{ role: 'user', content: req.body.message }],
    posthogDistinctId: req.userId,
    posthogProperties: {
      $session_id: sessionId  // Links to session replay
    }
  })

  res.json({ response: response.choices[0].message.content })
})

@app.route('/api/chat', methods=['POST'])
def chat():
    session_id = request.headers.get('X-POSTHOG-SESSION-ID')

    response = client.responses.create(
        model="gpt-5",
        messages=[{"role": "user", "content": request.json['message']}],
        posthog_distinct_id=current_user.id,
        posthog_properties={
            "$session_id": session_id  # Links to session replay
        }
    )

    return jsonify({
        "response": response.choices[0].message.content
    })

Option 2: Manual approach

If you prefer explicit control, retrieve the session ID and pass it in your request body:

// Frontend
import posthog from 'posthog-js'

const response = await fetch('/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: userInput,
    sessionId: posthog.getSessionId()
  })
})

// Backend
app.post('/api/chat', async (req, res) => {
  const { message, sessionId } = req.body

  const response = await openai.responses.create({
    model: 'gpt-5',
    messages: [{ role: 'user', content: message }],
    posthogDistinctId: req.userId,
    posthogProperties: {
      $session_id: sessionId  // Links to session replay
    }
  })

  res.json({ response: response.choices[0].message.content })
})

# Backend
@app.route('/api/chat', methods=['POST'])
def chat():
    data = request.json
    session_id = data.get('sessionId')

    response = client.responses.create(
        model="gpt-5",
        messages=[{"role": "user", "content": data['message']}],
        posthog_distinct_id=current_user.id,
        posthog_properties={
            "$session_id": session_id  # Links to session replay
        }
    )

    return jsonify({
        "response": response.choices[0].message.content
    })

Viewing linked replays

Once you've set up session linking, you can navigate from LLM generations to their corresponding session replays:

1. In the LLM analytics dashboard, find the generation or trace you're interested in
2. Click the session replay button to jump directly to the replay
3. Watch the user's interaction with your AI features in context

This linking helps you understand not just what your AI is doing, but how users are experiencing it in your application.