User & Usage Tracking

The StudyFetch Usage Tracking API provides comprehensive analytics and monitoring capabilities to track user activity, measure engagement, and analyze usage patterns across your organization.

Understanding User ID and Group ID

User ID is a unique identifier for each user that comes from your platform. StudyFetch accepts any user ID format that your system uses, allowing seamless integration with your existing user management system. This flexibility enables:

Platform Integration: Use your existing user IDs without modification - whether they’re UUIDs, email addresses, student IDs, or any other format
Individual Activity Tracking: Monitor specific user interactions with materials, components, and features
Personalized Analytics: Generate user-specific reports on study patterns, performance, and engagement
Progress Monitoring: Track individual learning progress across different materials and assessments
Usage Attribution: Link specific events and actions to individual users for detailed analysis

Important: StudyFetch doesn’t generate user IDs - it uses whatever user identifiers your platform provides, ensuring consistency across your systems. Group ID represents an organizational unit such as a class, school, district, or any custom grouping. This ID allows:

Aggregate Analytics: View combined usage statistics for all users within a group
Organizational Reporting: Generate reports at the class, school, or district level
Performance Comparison: Compare usage patterns and outcomes across different groups
Resource Allocation: Understand how different groups utilize StudyFetch features to optimize resource distribution

Usage Event Types

The API tracks various event types to provide comprehensive insights:

Material Events

material_created - When new study material is created
material_uploaded - When files are uploaded to the platform
material_processed - When materials are processed by AI
material_deleted - When materials are removed

Component Events

component_created - When study components (flashcards, tests, etc.) are generated
component_accessed - When users view or interact with components
component_deleted - When components are removed
component_usage - General component interaction events

Chat & Communication Events

chat_message_sent - When users send messages in AI chat
chat_session_started - When new chat sessions begin
chat_session_ended - When chat sessions conclude

Assessment Events

test_created - When practice tests are generated
test_started - When users begin assessments
test_completed - When tests are finished
test_question_answered - Individual question responses
test_retaken - When users retake assessments

Feature Usage Events

audio_recap_create - Audio summary generation
assignment_grader_create - Assignment grading events
student_performance - Performance tracking events

System Events

api_call - API endpoint usage
cache_hit - Cached response usage
sso_login - Single sign-on authentication
sso_logout - User logout events

Example Usage

import StudyfetchSDK from '@studyfetch/sdk';

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

// Track individual user progress
const userEvents = await client.v1.usage.listEvents({
  userId: '[email protected]',
  eventType: 'test_completed',
  startDate: '2024-01-01T00:00:00Z',
  endDate: '2024-12-31T23:59:59Z',
  limit: 100,
  offset: 0
});

// Generate monthly group summary
const groupSummary = await client.v1.usage.getSummary({
  period: 'monthly',
  startDate: '2024-01-01T00:00:00Z',
  endDate: '2024-12-31T23:59:59Z',
  groupBy: 'group'
});

// Monitor feature adoption
const featureUsage = await client.v1.usage.listEvents({
  eventType: 'audio_recap_create',
  limit: 1000,
  groupId: 'class-101'
});

// Get usage statistics
const stats = await client.v1.usage.getStats({
  startDate: '2024-01-01T00:00:00Z',
  endDate: '2024-12-31T23:59:59Z',
  userId: '[email protected]'
});

from studyfetch_sdk import StudyfetchSDK

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

# Track individual user progress
user_events = client.v1.usage.list_events(
    user_id="[email protected]",
    event_type="test_completed",
    start_date="2024-01-01T00:00:00Z",
    end_date="2024-12-31T23:59:59Z",
    limit=100,
    offset=0
)

# Generate monthly group summary
group_summary = client.v1.usage.get_summary(
    period="monthly",
    start_date="2024-01-01T00:00:00Z",
    end_date="2024-12-31T23:59:59Z",
    group_by="group"
)

# Monitor feature adoption
feature_usage = client.v1.usage.list_events(
    event_type="audio_recap_create",
    limit=1000,
    group_id="class-101"
)

# Get usage statistics
stats = client.v1.usage.get_stats(
    start_date="2024-01-01T00:00:00Z",
    end_date="2024-12-31T23:59:59Z",
    user_id="[email protected]"
)

import com.studyfetch.javasdk.client.StudyfetchSdkClient;
import com.studyfetch.javasdk.client.okhttp.StudyfetchSdkOkHttpClient;
import com.studyfetch.javasdk.models.v1.usage.UsageListEventsParams;
import com.studyfetch.javasdk.models.v1.usage.UsageGetSummaryParams;
import com.studyfetch.javasdk.models.v1.usage.UsageGetStatsParams;

StudyfetchSdkClient client = StudyfetchSdkOkHttpClient.builder()
    .apiKey("your-api-key")
    .baseUrl("https://studyfetchapi.com")
    .build();

// Track individual user progress
UsageListEventsParams eventParams = UsageListEventsParams.builder()
    .userId("[email protected]")
    .eventType(UsageListEventsParams.EventType.TEST_COMPLETED)
    .startDate("2024-01-01T00:00:00Z")
    .endDate("2024-12-31T23:59:59Z")
    .limit(100.0)
    .offset(0.0)
    .build();
client.v1().usage().listEvents(eventParams);

// Generate monthly group summary
UsageGetSummaryParams summaryParams = UsageGetSummaryParams.builder()
    .period(UsageGetSummaryParams.Period.MONTHLY)
    .startDate("2024-01-01T00:00:00Z")
    .endDate("2024-12-31T23:59:59Z")
    .groupBy(UsageGetSummaryParams.GroupBy.GROUP)
    .build();
client.v1().usage().getSummary(summaryParams);

// Monitor feature adoption
UsageListEventsParams featureParams = UsageListEventsParams.builder()
    .eventType(UsageListEventsParams.EventType.AUDIO_RECAP_CREATE)
    .limit(1000.0)
    .groupId("class-101")
    .build();
client.v1().usage().listEvents(featureParams);

// Get usage statistics
UsageGetStatsParams statsParams = UsageGetStatsParams.builder()
    .startDate("2024-01-01T00:00:00Z")
    .endDate("2024-12-31T23:59:59Z")
    .userId("[email protected]")
    .build();
client.v1().usage().getStats(statsParams);

using StudyfetchSDK;
using StudyfetchSDK.Models.V1.Usage;
using System;
using System.Threading.Tasks;

public class UsageExample
{
    public static async Task Main()
    {
        var client = new StudyfetchSDKClient("your-api-key");

        // Track individual user progress
        await client.V1.Usage.ListEvents(new UsageListEventsParams
        {
            UserID = "[email protected]",
            EventType = UsageListEventsParams.EventType.TestCompleted,
            StartDate = "2024-01-01T00:00:00Z",
            EndDate = "2024-12-31T23:59:59Z",
            Limit = 100,
            Offset = 0
        });

        // Generate monthly group summary
        await client.V1.Usage.GetSummary(new UsageGetSummaryParams
        {
            Period = UsageGetSummaryParams.Period.Monthly,
            StartDate = "2024-01-01T00:00:00Z",
            EndDate = "2024-12-31T23:59:59Z",
            GroupBy = UsageGetSummaryParams.GroupBy.Group
        });

        // Monitor feature adoption
        await client.V1.Usage.ListEvents(new UsageListEventsParams
        {
            EventType = UsageListEventsParams.EventType.AudioRecapCreate,
            Limit = 1000,
            GroupID = "class-101"
        });

        // Get usage statistics with optional filters
        await client.V1.Usage.GetStats(new UsageGetStatsParams
        {
            StartDate = "2024-01-01T00:00:00Z",
            EndDate = "2024-12-31T23:59:59Z",
            UserID = "[email protected]",
            ComponentType = "chat",       // Optional: Filter by component type
            ResourceID = "comp_abc123"    // Optional: Filter by component ID
        });
    }
}

Component API

REST API

User & Usage Tracking

Understanding User ID and Group ID

Usage Event Types

Material Events

Component Events

Chat & Communication Events

Assessment Events

Feature Usage Events

System Events

Example Usage

​Understanding User ID and Group ID

​Usage Event Types

​Material Events

​Component Events

​Chat & Communication Events

​Assessment Events

​Feature Usage Events

​System Events

​Example Usage

Understanding User ID and Group ID

Usage Event Types

Material Events

Component Events

Chat & Communication Events

Assessment Events

Feature Usage Events

System Events

Example Usage