Course Students 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 Course Students API returns the students enrolled in one or more courses as a paginated list of student records. You pass a set of course IDs and receive back the distinct users enrolled in any of them, deduplicated so that a student enrolled in several of the requested courses appears only once.

This query is intentionally lightweight: each row is a student (id, name, email), not an enrollment. If you need per-course learning metrics — completion rate, delivery state, access expiration — use the Student Course Progress query instead (see Comparison with studentCourseProgress below).

Available Queries

courseStudents

Returns a paginated list of the distinct students enrolled in the given courses.

Parameters:

Parameter	Type	Required	Description
courseIds	[String]!	Yes	IDs of the courses whose enrolled students to return
filter	StudentFilter	No	Filter criteria on the student record (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:

• StudentPage object with:
  • nodes: Array of Student objects
  • currentPage: Current page number
  • hasNextPage: Whether there are more pages
  • hasPreviousPage: Whether there are previous pages
  • nodesCount: Total number of distinct students matching the query
  • totalPages: Total number of pages

Example:

query {
  courseStudents(
    courseIds: ["course-123-uuid", "course-456-uuid"]
    page: 1
    perPage: 20
  ) {
    nodes {
      id
      name
      email
    }
    currentPage
    hasNextPage
    hasPreviousPage
    nodesCount
    totalPages
  }
}

Student Object

The Student object contains the following fields:

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

Comparison with studentCourseProgress

courseStudents and studentCourseProgress both start from course enrollments, but they answer different questions and return different types:

	courseStudents	studentCourseProgress
Question answered	Who is enrolled?	How far along is each enrollment?
Course scope	Multiple courses (courseIds: [String]!)	A single course (courseId: String!)
Returned type	StudentPage — one node per student	StudentCourseShipPage — one node per enrollment (StudentCourseShip)
Deduplication	A student enrolled in several of the requested courses appears once	One row per student-course enrollment
Progress fields	None (id, name, email only)	completionRate, completionPercentage, deliveryState, endedAt, plus nested user and course
Sorting	By the underlying student scope	Completion rate desc, then updated_at desc

Use courseStudents for a roster or audience list across courses; use studentCourseProgress when you need engagement and completion metrics for a specific course.

Filtering

The courseStudents query accepts a filter parameter of type StudentFilter, applied to the student records.

Filter Field	Type	Description
email	StringOperator	Filter by student email address
name	StringOperator	Filter by student name

StringOperator

The StringOperator used in filters has these operations:

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

Filter Examples

Find an enrolled student by email:

query {
  courseStudents(
    courseIds: ["course-123-uuid"]
    filter: {
      email: { eq: "alice@example.com" }
    }
  ) {
    nodes {
      id
      name
      email
    }
    nodesCount
  }
}

Search enrolled students by name across several courses:

query {
  courseStudents(
    courseIds: ["course-123-uuid", "course-456-uuid"]
    filter: {
      name: { contains: "wang" }
    }
  ) {
    nodes {
      id
      name
      email
    }
    nodesCount
  }
}

Authorization

courseStudents requires an API key carrying either the students:read or the members:read scope. An API key with either scope is sufficient.

Related Queries

• Student Course Progress Query — per-course completion and enrollment metrics
• Courses Query — course details
• Filtering Guide — general filtering documentation
• Pagination Guide — pagination best practices