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:

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

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

Best Practices

Always specify courseId: This is a required parameter that ensures you’re querying the correct course.
Use completion percentage for filtering: The completionPercentage field (0-100) is more intuitive than completionRate (0.0-1.0).
Batch queries have limits: When using the userId: { in: [...] } filter, limit the array to 100 items maximum.
Filter by delivery state: Consider filtering out expired enrollments for most use cases by using deliveryState: { eq: "delivered" }.
Combine filters for targeted queries: Use multiple filter criteria to narrow down results to specific student cohorts.
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.

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