Student Course Progress Query

Note: The Teachify Admin API is currently under development and not yet available for public use. This documentation is provided for preview purposes only.

Overview

The Student Course Progress API allows you to retrieve information about student learning progress in a specific course. You can view completion rates, enrollment status, and access expiration details for all students enrolled in a course.

Available Queries

studentCourseProgress

Returns a paginated list of student progress records for a specific course.

Parameters:

Parameter	Type	Required	Description
courseId	String!	Yes	The unique identifier of the course
filter	StudentCourseProgressFilter	No	Filter criteria (see Filtering)
page	Int	No	Page number for pagination
perPage	Int	No	Number of items per page (default: 20, max: 50)
limit	Int	No	Alternative to perPage

Returns:

• StudentCourseShipPage object with:
  • nodes: Array of StudentCourseShip objects
  • currentPage: Current page number
  • hasNextPage: Whether there are more pages
  • hasPreviousPage: Whether there are previous pages
  • nodesCount: Total number of items in the current page
  • totalPages: Total number of pages

Example:

query {
  studentCourseProgress(
    courseId: "course-123-uuid"
    page: 1
    perPage: 20
  ) {
    nodes {
      id
      user {
        id
        name
        email
      }
      course {
        id
        name
      }
      completionRate
      completionPercentage
      deliveryState
      endedAt
      createdAt
      updatedAt
    }
    currentPage
    hasNextPage
    totalPages
    nodesCount
  }
}

StudentCourseShip Object

The StudentCourseShip object contains the following fields:

Field	Type	Description
id	String!	Unique identifier for the enrollment record
user	User!	The student user object
course	Course!	The course object
completionRate	Float	Completion rate as decimal (0.0-1.0)
completionPercentage	Float	Completion percentage (0-100) for easier display
deliveryState	String	Current enrollment state: delivered, group_buying, pre_ordering, or expired
endedAt	Int	Unix timestamp when course access expires (null for lifetime access)
createdAt	Int!	Unix timestamp when the student enrolled
updatedAt	Int!	Unix timestamp of last update

User Object in Progress

Each progress record includes user information:

Field	Type	Description
id	String!	User’s unique identifier
name	String	User’s full name
email	String	User’s email address

Course Object in Progress

Each progress record includes basic course information:

Field	Type	Description
id	String!	Course’s unique identifier
name	String!	Course name

Detailed Query Structure

Below is a comprehensive view of fields available in the studentCourseProgress query:

query {
  studentCourseProgress(
    courseId: "course-123-uuid"
    filter: {
      completionPercentage: { gte: 50 }
      deliveryState: { eq: "delivered" }
    }
    page: 1
    perPage: 20
  ) {
    # Student progress data
    nodes {
      id                          # Enrollment record ID (String!)

      # User information
      user {
        id                        # User ID (String!)
        name                      # Full name (String)
        email                     # Email address (String)
      }

      # Course information
      course {
        id                        # Course ID (String!)
        name                      # Course name (String!)
      }

      # Progress metrics
      completionRate              # Decimal format 0.0-1.0 (Float)
      completionPercentage        # Percentage format 0-100 (Float)

      # Enrollment status
      deliveryState               # delivered, group_buying, pre_ordering, expired (String)
      endedAt                     # Access expiration timestamp (Int)

      # Timestamps
      createdAt                   # Enrollment date (Int!)
      updatedAt                   # Last updated (Int!)
    }

    # Pagination metadata
    currentPage                   # Current page number (Int!)
    hasNextPage                   # Whether there are more pages (Boolean!)
    hasPreviousPage               # Whether there are previous pages (Boolean!)
    nodesCount                    # Number of items in current page (Int!)
    totalPages                    # Total number of pages (Int!)
  }
}

Filtering

The studentCourseProgress query accepts a filter parameter of type StudentCourseProgressFilter. This allows you to narrow down results based on various criteria.

Filter Field	Type	Description
userId	StringOperator	Filter by specific user ID(s)
completionPercentage	IntOperator	Filter by completion percentage (0-100)
deliveryState	StringOperator	Filter by enrollment state
endedAt	IntOperator	Filter by access expiration date
createdAt	IntOperator	Filter by enrollment date
updatedAt	IntOperator	Filter by last update date

IntOperator

The IntOperator used for numeric filters has these operations:

Operation	Description
eq	Equal to
neq	Not equal to
gt	Greater than
gte	Greater than or equal to
lt	Less than
lte	Less than or equal to

StringOperator

The StringOperator used for string filters has these operations:

Operation	Description
eq	Equal to
neq	Not equal to
in	In a list of values (batch query, max 100 items)
nin	Not in a list of values
like	Match text values against a pattern using wildcards (case-sensitive)
contains	Contains text (case-insensitive)

Filter Examples

Find High-Performing Students

Query students with completion rate above 80%:

query {
  studentCourseProgress(
    courseId: "course-123-uuid"
    filter: {
      completionPercentage: { gt: 80 }
      deliveryState: { eq: "delivered" }
    }
  ) {
    nodes {
      user {
        id
        name
        email
      }
      completionPercentage
      updatedAt
    }
    nodesCount
  }
}

Find Students Needing Attention

Query students with low completion rate (below 30%):

query {
  studentCourseProgress(
    courseId: "course-123-uuid"
    filter: {
      completionPercentage: { lt: 30 }
      deliveryState: { eq: "delivered" }
    }
  ) {
    nodes {
      user {
        id
        name
        email
      }
      completionPercentage
      updatedAt
    }
  }
}

Find Students with Expiring Access

Query students whose access will expire within 30 days:

query {
  studentCourseProgress(
    courseId: "course-123-uuid"
    filter: {
      endedAt: {
        gte: 1704067200    # Current timestamp
        lte: 1706745600    # 30 days from now
      }
      deliveryState: { eq: "delivered" }
    }
  ) {
    nodes {
      user {
        id
        name
        email
      }
      completionPercentage
      endedAt
    }
  }
}

Query Multiple Students

Query progress for specific students using batch query:

query {
  studentCourseProgress(
    courseId: "course-123-uuid"
    filter: {
      userId: {
        in: ["user-1-uuid", "user-2-uuid", "user-3-uuid"]
      }
    }
  ) {
    nodes {
      user {
        id
        name
      }
      completionPercentage
      deliveryState
    }
  }
}

Query by Completion Range

Find students with moderate progress (50%-80%):

query {
  studentCourseProgress(
    courseId: "course-123-uuid"
    filter: {
      completionPercentage: {
        gte: 50
        lte: 80
      }
    }
  ) {
    nodes {
      user {
        id
        name
      }
      completionPercentage
    }
  }
}

Exclude Expired Enrollments

Query only active students (not expired):

query {
  studentCourseProgress(
    courseId: "course-123-uuid"
    filter: {
      deliveryState: { neq: "expired" }
    }
  ) {
    nodes {
      user {
        id
        name
      }
      completionPercentage
      deliveryState
    }
  }
}

Find Recently Active Students

Query students who have been active in the last 7 days:

query {
  studentCourseProgress(
    courseId: "course-123-uuid"
    filter: {
      updatedAt: { gte: 1703980800 }  # 7 days ago timestamp
    }
  ) {
    nodes {
      user {
        id
        name
      }
      completionPercentage
      updatedAt
    }
  }
}

Combined Filters

Query high-performing active students who recently updated their progress:

query {
  studentCourseProgress(
    courseId: "course-123-uuid"
    filter: {
      completionPercentage: { gte: 70 }
      deliveryState: { eq: "delivered" }
      updatedAt: { gte: 1701388800 }  # Last 30 days
    }
  ) {
    nodes {
      user {
        id
        name
        email
      }
      completionPercentage
      updatedAt
    }
    nodesCount
  }
}

Delivery States

The deliveryState field indicates the current status of a student’s course enrollment:

State	Description
delivered	Normal access - student can access the course
group_buying	Currently in group buying phase
pre_ordering	Course is in pre-order status
expired	Course access has expired

Use Cases

Track Course Engagement

Monitor overall course engagement by viewing completion rates across all students:

query {
  studentCourseProgress(
    courseId: "course-123-uuid"
    page: 1
    perPage: 50
  ) {
    nodes {
      user { name }
      completionPercentage
    }
    nodesCount
  }
}

Identify Students for Re-engagement

Find students who haven’t made progress recently:

query {
  studentCourseProgress(
    courseId: "course-123-uuid"
    filter: {
      completionPercentage: { lt: 50 }
      updatedAt: { lt: 1698796800 }  # 90 days ago
      deliveryState: { eq: "delivered" }
    }
  ) {
    nodes {
      user {
        id
        name
        email
      }
      completionPercentage
      updatedAt
    }
  }
}

Monitor Course Completion

Track students who have completed or nearly completed the course:

query {
  studentCourseProgress(
    courseId: "course-123-uuid"
    filter: {
      completionPercentage: { gte: 90 }
    }
  ) {
    nodes {
      user {
        id
        name
        email
      }
      completionPercentage
      createdAt
      updatedAt
    }
    nodesCount
  }
}

Pagination

Results are paginated to ensure optimal performance. Use the page and perPage parameters to navigate through results:

query {
  studentCourseProgress(
    courseId: "course-123-uuid"
    page: 2
    perPage: 25
  ) {
    nodes {
      user { name }
      completionPercentage
    }
    currentPage      # 2
    totalPages       # Total number of pages
    hasNextPage      # true if more pages available
    hasPreviousPage  # true if previous pages exist
    nodesCount       # Number of students in current page
  }
}

Sorting

Results are automatically sorted by:

1. Completion rate (descending) - highest completion first
2. Updated at (descending) - most recently active first

This ensures that the most engaged students appear at the top of the results.

Best Practices

1. Always specify courseId: This is a required parameter that ensures you’re querying the correct course.

2. Use completion percentage for filtering: The completionPercentage field (0-100) is more intuitive than completionRate (0.0-1.0).

3. Batch queries have limits: When using the userId: { in: [...] } filter, limit the array to 100 items maximum.

4. Filter by delivery state: Consider filtering out expired enrollments for most use cases by using deliveryState: { eq: "delivered" }.

5. Combine filters for targeted queries: Use multiple filter criteria to narrow down results to specific student cohorts.

6. Monitor access expiration: Use endedAt filters to identify students who need renewal reminders.

Error Handling

Common error scenarios:

• Course not found: If the specified courseId doesn’t exist or doesn’t belong to your school, an empty result set will be returned.
• Invalid filter values: Ensure numeric filters use appropriate operators and values.
• Batch size exceeded: Keep userId batch queries under 100 items to avoid errors.

Related Queries

• Courses Query - To get course details
• Users Query - To get user information
• Filtering Guide - General filtering documentation
• Pagination Guide - Pagination best practices