Create and manage student groups

You can use student groups to organize students into specific groups for enhanced teaching experiences, like targeted assignments and collaborative activities. Use the Classroom API to create, modify, and read student groups within a course on behalf of administrators and teachers.

You can create, update, delete, and read student groups using the following methods:

You can also add, remove, and read members within a student group using the following methods:

Access student groups methods in the Developer Preview Program

The student groups endpoints are in preview, meaning that you must be part of the Developer Preview Program (DPP) to make requests to them. For information on how to join the DPP, visit the preview features and roadmap page.

Endpoints in the DPP aren't exposed in standard client libraries and standard HTTP requests. After you join the DPP, you must include the preview label and preview version when making API requests. For the student groups endpoints, the preview label is DEVELOPER_PREVIEW and the preview version is V1_20250630_PREVIEW. For information on including the preview label and preview version in your application code, see the Access preview APIs page.

Licensing and eligibility requirements

To create, modify or delete student groups in a course and add or remove members from student groups, the following conditions must be met:

Reading student groups and its members

Administrators and teachers of a course can read student group data regardless of what license they are assigned. This means that requests to the ListStudentGroups and ListStudentGroupMembers endpoints are permitted on behalf of any administrator or teacher in a course.

Prerequisites

This guide provides code examples in Python, and assumes that you have the following:

  • A Google Cloud project. You can set one up following the instructions in the Python quickstart.
  • Added the following scopes to your project's OAuth consent screen:
    • https://www.googleapis.com/auth/classroom.rosters
    • https://www.googleapis.com/auth/classroom.rosters.readonly for read-only endpoints.
  • An ID of a course in which student groups should be managed. The course owner must have a Google Workspace for Education Plus license.
  • Access to a teacher's or administrator's credentials with a Google Workspace for Education Plus license.

Check user eligibility

The Classroom API provides the userProfiles.checkUserCapability endpoint to help you proactively determine whether a user is able to create and modify student groups and its members.

The userProfiles.checkUserCapability endpoint only evaluates whether a user is eligible to use a certain capability, such as modifying student groups. It doesn't offer any information about the course role. For example, even if a user has the CREATE_STUDENT_GROUP capability, if they are a student in the course, a request to the CreateStudentGroup endpoint won't succeed.

Python

def check_student_groups_update_capability(classroom_service, course_id):
    """Checks whether a user is able to create and modify student groups in a course."""

    capability = classroom_service.userProfiles().checkUserCapability(
        userId="me", # Can also be set to a different user's email address or ID
        capability="CREATE_STUDENT_GROUP",
        previewVersion="V1_20240930_PREVIEW" # Required while the method is in the DPP.
    ).execute()

    if capability.get("allowed"): # Retrieve the `allowed` boolean from the response.
        print("User is allowed to create and modify student groups.")
    else:
        print("User is not allowed to create and modify student groups.")

Manage student groups

Student groups can be created using the CreateStudentGroup endpoint.

Python

def create_student_group(classroom_service, course_id):
    body = {
        "title": "Team Blue"
    }

    response = classroom_service.courses().studentGroups().create(
        courseId=course_id,
        body=body,
        previewVersion="V1_20250630_PREVIEW",
    ).execute()

    print(response)

The response contains the id of the newly created student group, the courseId, and the student group title.

The student group id can be used to update or delete the individual student group.

Python

def update_student_group(classroom_service, course_id, student_group_id):
    body = {
        "title": "Team Green"
    }

    response = classroom_service.courses().studentGroups().patch(
        courseId=course_id,
        id=student_group_id,
        body=body,
        updateMask="title",
        previewVersion="V1_20250630_PREVIEW"
    ).execute()

    print(response)

def delete_student_group(classroom_service, course_id, student_group_id):
    response = classroom_service.courses().studentGroups().delete(
        courseId=course_id,
        id=student_group_id,
        previewVersion="V1_20250630_PREVIEW",
    ).execute()

    print(response)

You can retrieve the student groups within a course using the ListStudentGroups endpoint:

Python

def list_student_groups(classroom_service, course_id):
    results = classroom_service.courses().studentGroups().list(
        courseId=course_id,
        previewVersion="V1_20250630_PREVIEW"
    ).execute()

    studentGroups = results.get("studentGroups")

Manage student group members

Once the student group has successfully been created, you can add members to it.

Python

def add_student_group_member(classroom_service, course_id, student_group_id):
    body = {
        "userId": "student@schooldomain.com"
    }

    response = classroom_service.courses().studentGroups().studentGroupMembers().create(
        courseId=course_id,
        studentGroupId=student_group_id,
        body=body,
        previewVersion="V1_20250630_PREVIEW"
    ).execute()

    print(response)

If you'd like to remove a member from a student group, make a request like the following:

Python

def delete_student_group_member(classroom_service, course_id, student_group_id):
    response = classroom_service.courses().studentGroups().studentGroupMembers().delete(
        courseId=course_id,
        studentGroupId=student_group_id,
        userId="student@schooldomain.com",
        previewVersion="V1_20250630_PREVIEW"
    ).execute()
    print(response)

You can read the members within a group by making the following request:

Python

def list_student_group_members(classroom_service, course_id, student_group_id):
    results = classroom_service.courses().studentGroups().studentGroupMembers().list(
        courseId=course_id,
        studentGroupId=student_group_id,
        previewVersion="V1_20250630_PREVIEW"
    ).execute()

    print(results.get("studentGroupMembers"))

Each StudentGroupMember resource includes the courseId, studentGroupId, and userId of the group member.

Previous
Create & manage guardians