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

# Chat Analytics API

> Programmatically analyze chat usage and user engagement data

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.

<CodeGroup>
  ```javascript JavaScript theme={null}
  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'
  });
  ```

  ```python Python theme={null}
  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"
  })
  ```

  ```java Java theme={null}
  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);
      }
  }
  ```

  ```csharp C# theme={null}
  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"
          });
      }
  }
  ```
</CodeGroup>

### Parameters

<ParamField query="componentId" type="string">
  Component ID to analyze
</ParamField>

<ParamField query="endDate" type="datetime">
  End date for analysis (ISO 8601 format)
</ParamField>

<ParamField query="groupIds" type="array">
  Array of group IDs to filter by
</ParamField>

<ParamField query="modelKey" type="string">
  AI model to filter by (e.g., "gpt-4.1-2025-04-14")
</ParamField>

<ParamField query="organizationId" type="string">
  Organization ID to filter by
</ParamField>

<ParamField query="startDate" type="datetime">
  Start date for analysis (ISO 8601 format)
</ParamField>

<ParamField query="userId" type="string">
  User ID to filter by
</ParamField>

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

```json theme={null}
{
  "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.

<CodeGroup>
  ```javascript JavaScript theme={null}
  // 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
  ```

  ```python Python theme={null}
  # 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
  ```

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

  ```csharp C# theme={null}
  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
      }
  }
  ```
</CodeGroup>

## Get Component Analytics

Get analytics for a specific chat component.

<CodeGroup>
  ```javascript JavaScript theme={null}
  // 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`);
  });
  ```

  ```python Python theme={null}
  # 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")
  ```

  ```java Java theme={null}
  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");
  }
  ```

  ```csharp C# theme={null}
  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");
          }
      }
  }
  ```
</CodeGroup>