LMS Progress API Guide

Overview

The lms-progress API provides a unified endpoint for retrieving progress, enrollment, and financial metrics across the platform. The Teacher and Admin Dashboards use this data to display performance statistics. The endpoint returns two datasets:

Overall — Aggregated metrics for the entire platform.
Per category — Detailed metrics broken down by course category.

Authentication

The API supports two methods of authentication:

API Key (Recommended for server-to-server) — Pass your API key in the x-api-key header.
Session Cookie (For frontend clients) — Pass the browser session cookie.

Method 1: Using an API Key (Recommended)

Generate an API Key in the Kunci API sidebar under the Teacher Dashboard. Once generated, include it in your HTTP requests using the x-api-key header:

curl -H "x-api-key: lms_key_your_actual_key" \
     https://lms.terang.ai/api/lms-progress

Method 2: Using Session Cookies (Development)

To test the endpoint locally or via curl using browser cookies:

Sign in to the LMS dashboard via your browser.
Open the browser’s developer tools and copy the session cookie value (usually named authjs.session-token or similar).
Run the curl command below, replacing <cookie-value> with your token:

curl -H "Cookie: authjs.session-token=<cookie-value>" \
     https://lms.terang.ai/api/lms-progress

Requesting from the browser (Frontend)

When fetching the API from frontend React components, you must include credentials. This ensures the browser attaches session cookies to the request.

fetch('/api/lms-progress', {
  credentials: 'include' // Required to send cookies
})

Frontend integration guide

Use these TypeScript interfaces and React hooks to integrate the progress metrics into your dashboard page.

TypeScript type definitions

Define the structure of the API response to ensure strict type safety.

export interface LmsProgressResponse {
  success: boolean;
  data: {
    overall: OverallMetrics;
    perCategory: CategoryMetrics[];
  };
}

export interface OverallMetrics {
  totalDaftar: number; // Legacy
  totalBeli: number; // Legacy
  totalSelesai: number; // Legacy
  totalSertifikat: number; // Legacy
  totalClasses: number;
  totalCourses: number;
  totalStudents: number;
  completionRate: number;
  buyers30Days: number;
  revenue30Days: number;
  totalKum30Days: number;
  certificatesCount: number;
  peopleWithBadgeCount: number;
}

export interface CategoryMetrics {
  categoryId: number;
  categoryCode: string;
  categoryName: string;
  totalBeli: number; // Legacy
  totalSelesai: number; // Legacy
  totalSertifikat: number; // Legacy
  totalClasses: number;
  totalCourses: number;
  totalStudents: number;
  completionRate: number;
  buyers30Days: number;
  revenue30Days: number;
  totalKum30Days: number;
  certificatesCount: number;
  peopleWithBadgeCount: number;
}

Code example: React fetch hook

This example shows a custom React state approach to fetch, handle errors, and manage loading states:

import { useState, useEffect } from 'react';
import { LmsProgressResponse, OverallMetrics } from '@/types/progress';

export function useLmsProgress() {
  const [data, setData] = useState<LmsProgressResponse | null>(null);
  const [loading, setLoading] = useState<boolean>(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    async function loadProgress() {
      try {
        setLoading(true);
        const res = await fetch('/api/lms-progress', {
          credentials: 'include',
        });
        
        if (!res.ok) {
          if (res.status === 401 || res.status === 403) {
            throw new Error('Access denied. Log in with an authorized account.');
          }
          throw new Error(`Server returned status: ${res.status}`);
        }

        const payload: LmsProgressResponse = await res.json();
        if (!payload.success) {
          throw new Error('Failed to load metrics data.');
        }

        setData(payload);
      } catch (err: any) {
        setError(err.message || 'An unknown error occurred.');
      } finally {
        setLoading(false);
      }
    }

    loadProgress();
  }, []);

  return { data, loading, error };
}

Technical calculation logic

The backend uses Drizzle ORM to perform queries and aggregates. Here is how the complex metrics are processed:

Completion rate calculation

To calculate the completionRate, the API computes the progress of each student in each enrolled course and averages them. It runs a SQL CTE (Common Table Expression) to perform the math:

Calculate total chapters per course: Counts all chapters within modules mapped to the course.
Calculate completed chapters per student: Counts unique records in student_progress where completed = true.
Compute enrollment progress: Divides the completed chapters by the total chapters. If a course has 0 chapters, progress defaults to 0.
Average the progress: Calculates the average progress across all enrollments.

The SQL CTE query executed by the database:

WITH course_chapters AS (
  SELECT m.course_id, COUNT(c.id)::float AS total_chapters
  FROM chapters c
  JOIN modules m ON c.module_id = m.id
  GROUP BY m.course_id
),
student_completed AS (
  SELECT sp.student_id, sp.course_id, COUNT(DISTINCT sp.chapter_id)::float AS completed_chapters
  FROM student_progress sp
  WHERE sp.completed = true
  GROUP BY sp.student_id, sp.course_id
),
enrollment_progress AS (
  SELECT 
    CASE 
      WHEN COALESCE(cc.total_chapters, 0) > 0 
      THEN (COALESCE(sc.completed_chapters, 0) / cc.total_chapters) * 100 
      ELSE 0 
    END as progress
  FROM student_enrollments se
  LEFT JOIN course_chapters cc ON se.course_id = cc.course_id
  LEFT JOIN student_completed sc ON se.student_id = sc.student_id AND se.course_id = sc.course_id
)
SELECT COALESCE(AVG(progress), 0)::float as "avgProgress"
FROM enrollment_progress;

Getting Started

Integration

LMS Guides

LMS Progress API Guide

Overview

Authentication

Method 1: Using an API Key (Recommended)

Method 2: Using Session Cookies (Development)

Requesting from the browser (Frontend)

Frontend integration guide

TypeScript type definitions

Code example: React fetch hook

Technical calculation logic

Completion rate calculation

​Overview

​Authentication

​Method 1: Using an API Key (Recommended)

​Method 2: Using Session Cookies (Development)

​Requesting from the browser (Frontend)

​Frontend integration guide

​TypeScript type definitions

​Code example: React fetch hook

​Technical calculation logic

​Completion rate calculation

Overview

Authentication

Method 1: Using an API Key (Recommended)

Method 2: Using Session Cookies (Development)

Requesting from the browser (Frontend)

Frontend integration guide

TypeScript type definitions

Code example: React fetch hook

Technical calculation logic

Completion rate calculation