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

To access the student groups methods in preview, you must do the following:

  • Join the Developer Preview Program (DPP).
  • Set up your client library to access preview features. Methods in the DPP aren't exposed in standard client libraries and standard HTTP requests. After you successfully join the DPP, you can access and download the student groups client libraries for specific programming languages. See the Access preview APIs page to learn how to set up your client library of choice with a preview version and label.
  • Set the preview version and preview label when making API requests. For the student groups methods, the preview version is V1_20250630_PREVIEW and the preview label is DEVELOPER_PREVIEW. You can find examples of API requests with the preview version in the Manage student groups section.

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.

Code example 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.

If you followed the Python quickstart as a starting point, modify the Classroom service to access preview methods.

Python

classroom_service = googleapiclient.discovery.build(
    serviceName='classroom',
    version='v1',
    credentials=creds,
    static_discovery=False,
    discoveryServiceUrl='https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key=API_KEY')

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