Chat Analytics API

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'
});

from studyfetch_sdk import StudyfetchSDK
from datetime import datetime

client = StudyfetchSDK(
    api_key="your-api-key",
    base_url="https://studyfetchapi.com",
)

# Basic analytics for the last 30 days
analytics = client.v1.chat_analytics.analyze()

print(f"Analytics generated at: {analytics.generated_at}")
print(f"Summary: {analytics.summary}")
print(f"User stats: {analytics.user_stats}")

# With specific parameters
filtered_analytics = client.v1.chat_analytics.analyze({
    "startDate": datetime(2024, 1, 1),
    "endDate": datetime(2024, 1, 31),
    "organizationId": "org-123",
    "userId": "user-456",
    "groupIds": ["group-1", "group-2"],
    "componentId": "chat-component-789",
    "modelKey": "gpt-4.1-2025-04-14"
})

import com.studyfetch.javasdk.client.StudyfetchSdkClient;
import com.studyfetch.javasdk.client.okhttp.StudyfetchSdkOkHttpClient;
import com.studyfetch.javasdk.models.v1.chatanalytics.ChatAnalyticAnalyzeParams;
import com.studyfetch.javasdk.models.v1.chatanalytics.ChatAnalyticsResponse;
import java.time.LocalDateTime;
import java.time.OffsetDateTime;
import java.util.List;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        StudyfetchSdkClient client = StudyfetchSdkOkHttpClient.fromEnv();

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

        System.out.println("Analytics generated at: " + analytics.generatedAt());
        System.out.println("Summary: " + analytics.summary());
        System.out.println("User stats: " + analytics.userStats());

        // With specific parameters
        ChatAnalyticAnalyzeParams params = ChatAnalyticAnalyzeParams.builder()
                .startDate(OffsetDateTime.from(LocalDateTime.of(2024, 1, 1, 0, 0)))
                .endDate(OffsetDateTime.from(LocalDateTime.of(2024, 1, 31, 23, 59)))
                .organizationId("org-123")
                .userId("user-456")
                .groupIds(List.of("group-1", "group-2"))
                .componentId("chat-component-789")
                .modelKey("gpt-4.1-2025-04-14")
                .build();

        ChatAnalyticsResponse filteredAnalytics = client.v1().chatAnalytics().analyze(params);
    }
}

using StudyfetchSDK;
using StudyfetchSDK.Models.V1.ChatAnalytics;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

public class AnalyzeChatAnalytics
{
    public static async Task Main(string[] args)
    {
        StudyfetchSDKClient client = new()
        {
            APIKey = Environment.GetEnvironmentVariable("STUDYFETCH_API_KEY"),
            BaseUrl = new Uri("https://studyfetchapi.com")
        };

        // Basic analytics (all parameters are optional)
        var analytics = await client.V1.ChatAnalytics.Analyze(new ChatAnalyticsAnalyzeParams());
        
        Console.WriteLine($"Analytics generated at: {analytics.GeneratedAt}");
        Console.WriteLine($"Summary: {analytics.Summary}");
        Console.WriteLine($"User stats: {analytics.UserStats}");

        // With specific parameters
        var filteredAnalytics = await client.V1.ChatAnalytics.Analyze(new ChatAnalyticsAnalyzeParams()
        {
            StartDate = new DateTime(2024, 1, 1),
            EndDate = new DateTime(2024, 1, 31),
            OrganizationID = "org-123",
            UserID = "user-456",
            GroupIDs = new List<string> { "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": "[email protected]",
      "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

# Export all analytics data
csv_data = client.v1.chat_analytics.export()

# Save to file
with open("chat-analytics.csv", "w") as f:
    f.write(csv_data)

# Export with filters
filtered_csv = client.v1.chat_analytics.export({
    "startDate": datetime(2024, 1, 1),
    "endDate": datetime(2024, 1, 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

import java.io.FileWriter;
import java.io.IOException;
import com.studyfetch.javasdk.models.v1.chatanalytics.ChatAnalyticExportParams;
import java.time.LocalDateTime;
import java.time.OffsetDateTime;
import java.util.List;

// Export all analytics data
String csvData = client.v1().chatAnalytics().export();

// Save to file
try (FileWriter writer = new FileWriter("chat-analytics.csv")) {
    writer.write(csvData);
}

// Export with filters
ChatAnalyticExportParams exportParams = ChatAnalyticExportParams.builder()
        .startDate(OffsetDateTime.from(LocalDateTime.of(2024, 1, 1, 0, 0)))
        .endDate(OffsetDateTime.from(LocalDateTime.of(2024, 1, 31, 23, 59)))
        .organizationId("org-123")
        .groupIds(List.of("group-1", "group-2"))
        .modelKey("gpt-4.1-2025-04-14")
        .build();

String filteredCsv = client.v1().chatAnalytics().export(exportParams);

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

using StudyfetchSDK;
using StudyfetchSDK.Models.V1.ChatAnalytics;
using System;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;

public class ExportChatAnalytics
{
    public static async Task ExportAnalytics()
    {
        StudyfetchSDKClient client = new()
        {
            APIKey = Environment.GetEnvironmentVariable("STUDYFETCH_API_KEY"),
            BaseUrl = new Uri("https://studyfetchapi.com")
        };

        // Export all analytics data
        string csvData = await client.V1.ChatAnalytics.Export(new ChatAnalyticsExportParams());
        
        // Save to file
        await File.WriteAllTextAsync("chat-analytics.csv", csvData);

        // Export with filters
        string filteredCsv = await client.V1.ChatAnalytics.Export(new ChatAnalyticsExportParams()
        {
            StartDate = new DateTime(2024, 1, 1),
            EndDate = new DateTime(2024, 1, 31),
            OrganizationID = "org-123",
            GroupIDs = new List<string> { "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`);
});

# Get analytics for a specific component
component_analytics = client.v1.chat_analytics.get_component({
    "componentId": "chat-component-789",
    "startDate": datetime(2024, 1, 1),
    "endDate": datetime(2024, 1, 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
})

print(f"Component: {component_analytics.component_id}")
print(f"Total messages: {component_analytics.summary.total_messages}")
print(f"Natural language summary: {component_analytics.summary.summary}")

# User-level statistics for this component
for stat in component_analytics.user_stats:
    print(f"User {stat.user_id}: {stat.total_messages} messages")

import com.studyfetch.javasdk.models.v1.chatanalytics.ChatAnalyticGetComponentParams;
import com.studyfetch.javasdk.models.v1.chatanalytics.ChatAnalyticsResponse;
import java.time.LocalDateTime;
import java.time.OffsetDateTime;
import java.util.List;

// Get analytics for a specific component
ChatAnalyticGetComponentParams componentParams = ChatAnalyticGetComponentParams.builder()
        .componentId("chat-component-789")
        .startDate(OffsetDateTime.from(LocalDateTime.of(2024, 1, 1, 0, 0)))
        .endDate(OffsetDateTime.from(LocalDateTime.of(2024, 1, 31, 23, 59)))
        .userId("user-456") // Optional: filter by user
        .groupIds(List.of("group-1")) // Optional: filter by groups
        .modelKey("gpt-4.1-2025-04-14") // Optional: filter by model
        .build();

ChatAnalyticsResponse componentAnalytics = client.v1().chatAnalytics()
        .getComponent(componentParams);

System.out.println("Component: " + componentParams.componentId());
System.out.println("Total messages: " + componentAnalytics.summary().totalMessages());
System.out.println("Natural language summary: " + componentAnalytics.summary().summary());

// User-level statistics for this component
for (ChatAnalyticsResponse.UserStat stat : componentAnalytics.userStats()) {
    System.out.println("User " + stat.userId() + ": " + stat.totalMessages() + " messages");
}

using StudyfetchSDK;
using StudyfetchSDK.Models.V1.ChatAnalytics;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

public class GetComponentAnalytics
{
    public static async Task GetComponentStats()
    {
        StudyfetchSDKClient client = new()
        {
            APIKey = Environment.GetEnvironmentVariable("STUDYFETCH_API_KEY"),
            BaseUrl = new Uri("https://studyfetchapi.com")
        };

        // Get analytics for a specific component
        var componentAnalytics = await client.V1.ChatAnalytics.GetComponent(new ChatAnalyticsGetComponentParams()
        {
            ComponentID = "chat-component-789",
            StartDate = new DateTime(2024, 1, 1),
            EndDate = new DateTime(2024, 1, 31),
            UserID = "user-456", // Optional: filter by user
            GroupIDs = new List<string> { "group-1" }, // Optional: filter by groups
            ModelKey = "gpt-4.1-2025-04-14" // Optional: filter by model
        });

        Console.WriteLine($"Natural language summary: {componentAnalytics.Summary.Summary1}");

        // User-level statistics for this component
        foreach (var stat in componentAnalytics.UserStats)
        {
            Console.WriteLine($"User {stat.UserID}: {stat.TotalMessages} messages");
        }
    }
}

Component API

REST API

Key Features

Analyze Chat Analytics

Parameters

Response Structure

Export Analytics Data

Get Component Analytics

​Key Features

​Analyze Chat Analytics

​Parameters

​Response Structure

​Export Analytics Data

​Get Component Analytics

Key Features

Analyze Chat Analytics

Parameters

Response Structure

Export Analytics Data

Get Component Analytics