Skip to main content
The Chat Analytics API provides direct access to analyze chat usage patterns, user engagement metrics, and export analytics data. These endpoints allow you to build custom analytics dashboards or integrate chat metrics into your existing reporting systems.

​
Key Features

  • Flexible Filtering: Filter by date ranges, users, groups, components, and AI models
  • Comprehensive Metrics: Get detailed usage statistics and engagement data
  • Natural Language Summaries: AI-generated insights about usage patterns
  • CSV Export: Export raw data for external analysis
  • Component-Specific Analysis: Analyze individual chat components

​
Analyze Chat Analytics

Get comprehensive analytics and user statistics for chat usage. 
import StudyfetchSDK from '@studyfetch/sdk';

const client = new StudyfetchSDK({
  apiKey: 'your-api-key',
  baseURL: 'https://studyfetchapi.com',
});

// Basic analytics for the last 30 days
const analytics = await client.v1.chatAnalytics.analyze();

console.log('Analytics generated at:', analytics.generatedAt);
console.log('Summary:', analytics.summary);
console.log('User stats:', analytics.userStats);

// With specific parameters
const filteredAnalytics = await client.v1.chatAnalytics.analyze({
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
  organizationId: 'org-123',
  userId: 'user-456',
  groupIds: ['group-1', 'group-2'],
  componentId: 'chat-component-789',
  modelKey: 'gpt-4.1-2025-04-14'
});

​
Parameters

​
componentId
string
Component ID to analyze
​
endDate
datetime
End date for analysis (ISO 8601 format)
​
groupIds
array
Array of group IDs to filter by
​
modelKey
string
AI model to filter by (e.g., “gpt-4.1-2025-04-14”)
​
organizationId
string
Organization ID to filter by
​
startDate
datetime
Start date for analysis (ISO 8601 format)
​
userId
string
User ID to filter by

​
Response Structure

The response includes comprehensive analytics data with message grading metrics:
  • Message Grading Scores (1-4 scale):
    • Prompting Score: Measures how well users craft their prompts and questions
    • Responsibility Score: Measures how responsibly users interact with the AI
    • Score distributions show the count of messages at each score level
{
  "generatedAt": "2024-01-31T23:59:59Z",
  "summary": {
    "totalMessages": 15420,
    "totalSessions": 892,
    "totalUsers": 156,
    "averageMessagesPerUser": 98.8,
    "topTopics": [
      "Python programming",
      "Data structures",
      "Machine learning basics"
    ],
    "summary": "Chat usage increased by 35% this month with strong engagement in programming topics. Students are particularly active during evening hours.",
    "engagement": {
      "peakHours": ["19:00-21:00"],
      "averageResponseTime": 1.2,
      "satisfactionScore": 4.6
    },
    "overallAveragePromptingScore": 3.1,
    "overallAverageResponsibilityScore": 3.7,
    "overallPromptingDistribution": {
      "1": 145,
      "2": 412,
      "3": 1823,
      "4": 892
    },
    "overallResponsibilityDistribution": {
      "1": 23,
      "2": 98,
      "3": 1245,
      "4": 1906
    }
  },
  "userStats": [
    {
      "userId": "user-123",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "groupIds": ["group-1"],
      "totalMessages": 245,
      "totalSessions": 18,
      "averageMessagesPerSession": 13.6,
      "averageSessionDuration": 25.5,
      "firstActive": "2024-01-05T10:30:00Z",
      "lastActive": "2024-01-30T18:45:00Z",
      "topTopics": [
        "Python functions",
        "Object-oriented programming"
      ],
      "totalGradedMessages": 142,
      "averagePromptingScore": 3.2,
      "averageResponsibilityScore": 3.8,
      "promptingDistribution": {
        "1": 12,
        "2": 28,
        "3": 67,
        "4": 35
      },
      "responsibilityDistribution": {
        "1": 2,
        "2": 8,
        "3": 45,
        "4": 87
      }
    }
  ]
}

​
Export Analytics Data

Export chat analytics data as CSV for external analysis or reporting. 
// Export all analytics data
const csvData = await client.v1.chatAnalytics.export();

// Save to file
const fs = require('fs');
fs.writeFileSync('chat-analytics.csv', csvData);

// Export with filters
const filteredCsv = await client.v1.chatAnalytics.export({
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
  organizationId: 'org-123',
  groupIds: ['group-1', 'group-2'],
  modelKey: 'gpt-4.1-2025-04-14'
});

// The CSV includes columns for:
// - userId, userName, userEmail
// - sessionId, sessionStart, sessionEnd
// - messageCount, messageTimestamps
// - topics, modelUsed
// - groupIds, componentId

​
Get Component Analytics

Get analytics for a specific chat component. 
// Get analytics for a specific component
const componentAnalytics = await client.v1.chatAnalytics.getComponent({
  componentId: 'chat-component-789',
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
  userId: 'user-456', // Optional: filter by user
  groupIds: ['group-1'], // Optional: filter by groups
  modelKey: 'gpt-4.1-2025-04-14' // Optional: filter by model
});

console.log(`Component: ${componentAnalytics.componentId}`);
console.log(`Total messages: ${componentAnalytics.summary.totalMessages}`);
console.log(`Natural language summary: ${componentAnalytics.summary.summary}`);

// User-level statistics for this component
componentAnalytics.userStats.forEach(stat => {
  console.log(`User ${stat.userId}: ${stat.totalMessages} messages`);
});
⌘I