# User Metrics & Analytics

> Understand user behavior, track engagement patterns, and optimize AI experiences with detailed user analytics

Analyze how users interact with your AI features through comprehensive user metrics. Track engagement patterns, identify power users, understand usage trends, and optimize experiences based on real user behavior data.

### Key User Metrics

<CardGroup cols={2}>
<Card title="Active Users" icon="users">
  Daily, weekly, and monthly active users
  Track user growth and retention trends
</Card>
<Card title="Session Analytics" icon="git-branch">
  Session length, depth, and engagement
  Understand conversation patterns
</Card>
<Card title="Usage Patterns" icon="activity">
  Request frequency, timing, and features used
  Identify most valuable use cases
</Card>
<Card title="User Satisfaction" icon="heart">
  Feedback scores, retry rates, and completion rates
  Measure AI experience quality
</Card>
</CardGroup>

## User Identification & Tracking

### Setting User IDs
Track users across sessions and requests:

<CodeGroup>
```typescript TypeScript
await client.chat.completions.create({
  model: "gpt-4o/openai",
  messages: [{ role: "user", content: "Hello!" }],
  headers: {
    "Helicone-User-Id": "user-12345"
  }
});
```

```python Python
response = client.chat.completions.create(
    model="gpt-4o/openai",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_headers={
        "Helicone-User-Id": "user-12345"
    }
)
```

```bash cURL
curl https://ai-gateway.helicone.ai/ai/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HELICONE_API_KEY" \
  -H "Helicone-User-Id: user-12345" \
  -d '{"model": "gpt-4o/openai", "messages": [...]}'
```
</CodeGroup>

### User Properties
Enrich user data with additional context:

```typescript
// Add user segmentation data
{
  headers: {
    "Helicone-User-Id": "user-12345",
    "Helicone-Property-UserTier": "premium",
    "Helicone-Property-UserType": "business",
    "Helicone-Property-SignupDate": "2024-01-15",
    "Helicone-Property-Industry": "healthcare"
  }
}
```

## User Behavior Analytics

### Usage Patterns
Understand how users interact with your AI:

```json
{
  "user_behavior": {
    "avg_requests_per_day": 24,
    "peak_usage_hours": [9, 14, 16],
    "session_length_avg": "12 minutes",
    "favorite_features": ["chat", "summary", "analysis"],
    "model_preferences": ["gpt-4o/openai", "claude-3.5-sonnet-v2/anthropic"]
  }
}
```

### Engagement Metrics
Track how engaged users are with your AI features:

<Tabs>
  <Tab title="Session Metrics">
    - **Session duration** - Time spent in conversations
    - **Messages per session** - Conversation depth
    - **Return sessions** - Users coming back within 24h
    - **Session completion rate** - Conversations finished vs abandoned
  </Tab>
  
  <Tab title="Request Patterns">
    - **Request frequency** - How often users make requests
    - **Request complexity** - Token length and reasoning difficulty
    - **Feature usage** - Which AI features are most popular
    - **Model stickiness** - User preference for specific models
  </Tab>
  
  <Tab title="Satisfaction Indicators">
    - **Retry rate** - How often users retry the same request
    - **Feedback scores** - Explicit user ratings
    - **Completion rate** - Requests that achieve user goals
    - **Follow-up questions** - Indicator of engagement
  </Tab>
</Tabs>

## User Segmentation

### Automatic Segmentation
Helicone automatically groups users based on behavior:

<CardGroup cols={2}>
<Card title="Power Users" icon="zap">
  High request volume, long sessions
  Top 10% of users by usage
</Card>
<Card title="Casual Users" icon="coffee">
  Moderate usage, shorter sessions
  Majority of user base
</Card>
<Card title="New Users" icon="user-plus">
  Recent signups, learning patterns
  First 30 days of usage
</Card>
<Card title="At-Risk Users" icon="alert-triangle">
  Declining usage, potential churn
  Require retention efforts
</Card>
</CardGroup>

### Custom Segmentation
Create segments based on your business logic:

```typescript
// Business tier segmentation
{
  "free_tier": {
    "monthly_request_limit": 1000,
    "features": ["basic_chat"],
    "support_level": "community"
  },
  "pro_tier": {
    "monthly_request_limit": 10000,
    "features": ["chat", "analysis", "summaries"],
    "support_level": "email"
  },
  "enterprise_tier": {
    "monthly_request_limit": "unlimited",
    "features": ["all"],
    "support_level": "priority"
  }
}
```

## User Journey Analysis

### Onboarding Analytics
Track how new users adopt your AI features:

<AccordionGroup>
  <Accordion title="First Session Analysis">
    **Key Metrics:**
    - Time to first request
    - First request success rate
    - Features discovered in first session
    - Session length and engagement
    
    **Optimization Goals:**
    - Reduce time to value
    - Increase first-session success
    - Guide feature discovery
  </Accordion>
  
  <Accordion title="Activation Milestones">
    **Milestone Tracking:**
    - First successful request
    - First multi-turn conversation
    - First use of advanced features
    - First week retention
    
    **Success Indicators:**
    - Users reaching activation milestones
    - Time to reach each milestone
    - Drop-off points in journey
  </Accordion>
  
  <Accordion title="Feature Adoption">
    **Adoption Funnel:**
    - Users aware of feature
    - Users who try feature
    - Users who adopt feature regularly
    - Users who become power users
    
    **Insights:**
    - Which features drive retention
    - Barriers to feature adoption
    - Optimal feature introduction timing
  </Accordion>
</AccordionGroup>

### Usage Evolution
Track how user behavior changes over time:

```json
{
  "user_evolution": {
    "week_1": {
      "requests_per_day": 3,
      "avg_session_length": "5 min",
      "features_used": ["chat"],
      "satisfaction_score": 7.2
    },
    "week_4": {
      "requests_per_day": 12,
      "avg_session_length": "15 min", 
      "features_used": ["chat", "analysis", "summary"],
      "satisfaction_score": 8.7
    },
    "week_12": {
      "requests_per_day": 28,
      "avg_session_length": "22 min",
      "features_used": ["all_features"],
      "satisfaction_score": 9.1
    }
  }
}
```

## Cohort Analysis

### User Cohorts
Group users by signup date to track retention:

| Cohort | Week 1 | Week 2 | Week 4 | Week 8 | Week 12 |
|--------|--------|--------|--------|--------|---------|
| Jan 2024 | 100% | 78% | 65% | 52% | 48% |
| Feb 2024 | 100% | 82% | 71% | 58% | 54% |
| Mar 2024 | 100% | 85% | 74% | 61% | - |

### Retention Insights
Understand what drives long-term usage:

- **High retention features** - Features that keep users coming back
- **Churn indicators** - Behaviors that predict user departure
- **Activation thresholds** - Usage levels that predict retention
- **Seasonal patterns** - How retention varies by time of year

## User Experience Metrics

### Quality Indicators
Measure the quality of AI interactions:

<CardGroup cols={2}>
<Card title="Success Rate" icon="check-circle">
  Percentage of requests that achieve user goals
  Track by user segment and feature
</Card>
<Card title="Response Quality" icon="star">
  User ratings and feedback scores
  Automated quality assessments
</Card>
<Card title="Task Completion" icon="target">
  Rate of successful task completion
  Multi-step workflow success rates  
</Card>
<Card title="User Satisfaction" icon="smile">
  Overall satisfaction scores
  Net Promoter Score (NPS) tracking
</Card>
</CardGroup>

### Friction Points
Identify where users struggle:

```json
{
  "friction_analysis": {
    "high_retry_requests": {
      "feature": "document_analysis",
      "retry_rate": 23,
      "common_issues": ["format_errors", "timeout"]
    },
    "abandoned_sessions": {
      "avg_abandonment_point": "4th message",
      "common_patterns": ["long_wait_time", "unclear_response"]
    },
    "error_hotspots": {
      "rate_limits": "15% of power users affected",
      "model_errors": "2.3% of requests fail"
    }
  }
}
```

## Personalization Insights

### User Preferences
Track individual user preferences:

- **Preferred models** - Which models users choose most often
- **Communication style** - Formal vs casual interaction patterns
- **Feature usage** - Which features each user finds valuable
- **Session timing** - When users are most active

### Adaptive Experiences
Use metrics to personalize experiences:

```typescript
// Personalized model selection based on user history
const getUserPreferredModel = (userId: string) => {
  const userMetrics = getUserMetrics(userId);
  
  if (userMetrics.prefers_speed) {
    return "gpt-4o-mini/openai,gemini-flash/google";
  }
  
  if (userMetrics.prefers_quality) {
    return "claude-3.5-sonnet-v2/anthropic,gpt-4o/openai";
  }
  
  return "gpt-4o-mini/openai,claude-3.5-haiku/anthropic";
};
```

## Comparative Analytics

### User Benchmarking
Compare user performance against benchmarks:

- **Usage vs peers** - How users compare to similar cohorts
- **Efficiency metrics** - Requests per goal achieved
- **Feature adoption** - Adoption rate vs typical users
- **Satisfaction vs average** - Experience quality comparison

### A/B Testing
Test improvements with user metrics:

<CodeGroup>
```typescript Feature Test
// A/B test new feature with user segments
const experimentVariant = getUserExperiment(userId, 'new_chat_ui');

if (experimentVariant === 'variant_a') {
  // Show improved chat interface
  return <NewChatUI />;
} else {
  // Show current interface  
  return <CurrentChatUI />;
}
```

```typescript Model Test
// Test model preference by user segment
const modelTest = getUserExperiment(userId, 'model_selection');

const model = modelTest === 'claude_first' 
  ? "claude-3.5-sonnet-v2/anthropic,gpt-4o/openai"
  : "gpt-4o/openai,claude-3.5-sonnet-v2/anthropic";

await client.chat.completions.create({ model, messages });
```
</CodeGroup>

## User Lifecycle Management

### Lifecycle Stages
Track users through their journey:

<Tabs>
  <Tab title="Acquisition">
    - **Source tracking** - How users discovered your AI
    - **First interaction** - Initial experience quality
    - **Onboarding completion** - Setup and first success
  </Tab>
  
  <Tab title="Activation">
    - **Feature discovery** - Key features adopted
    - **Usage milestones** - Regular usage patterns
    - **Value realization** - First significant success
  </Tab>
  
  <Tab title="Retention">
    - **Regular usage** - Consistent engagement patterns
    - **Feature expansion** - Adopting additional features
    - **Satisfaction maintenance** - Ongoing positive experience
  </Tab>
  
  <Tab title="Growth">
    - **Power user behavior** - High engagement levels
    - **Advocacy indicators** - Referrals and recommendations
    - **Premium adoption** - Upgrade to paid features
  </Tab>
</Tabs>

## Reporting & Insights

### Automated Reports
Receive regular user analytics:

- **Daily user activity** - Active users and key metrics
- **Weekly trends** - User behavior patterns and changes  
- **Monthly insights** - Deep analysis and recommendations
- **Quarterly reviews** - Strategic insights and planning

### Custom Dashboards
Create views tailored to your needs:

<CardGroup cols={2}>
<Card title="Product Dashboard" icon="users">
  User engagement, feature adoption, satisfaction
  Focus on product-market fit metrics
</Card>
<Card title="Growth Dashboard" icon="trending-up">
  Acquisition, activation, retention metrics
  Track growth funnel performance
</Card>
<Card title="Support Dashboard" icon="headphones">
  User issues, friction points, satisfaction
  Optimize user support and experience
</Card>
<Card title="Business Dashboard" icon="bar-chart">
  Revenue per user, lifetime value, churn
  Business impact and financial metrics
</Card>
</CardGroup>

## Privacy & Compliance

### Data Privacy
Protect user privacy while gathering insights:

- **Anonymized analytics** - Remove personally identifiable information
- **Consent management** - Respect user privacy preferences
- **Data retention** - Automatic cleanup of old user data
- **Compliance reporting** - GDPR, CCPA, and other regulations

### Ethical Considerations
Responsible user analytics practices:

- **Transparent data usage** - Clear communication about data collection
- **User benefit focus** - Use insights to improve user experience
- **Bias detection** - Monitor for unfair treatment of user segments
- **Opt-out options** - Allow users to limit data collection

## Next Steps

<CardGroup cols={2}>
<Card title="Set Up User Tracking" icon="user" href="/features/sessions">
  Implement user IDs and session tracking
</Card>
<Card title="Custom Properties" icon="tag" href="/features/advanced-usage/custom-properties">
  Add user segmentation and metadata
</Card>
<Card title="Feedback Collection" icon="message-circle" href="/features/advanced-usage/feedback">
  Gather user satisfaction data
</Card>
<Card title="A/B Testing" icon="git-branch" href="/experiments/overview">
  Test improvements with user segments
</Card>
</CardGroup>

User metrics provide crucial insights for building successful AI products. Use this data to understand user needs, optimize experiences, and drive product growth.