The Administrative Burden of End-of-Year
For school district IT administrators and technology coaches, the end of the academic year is a logistical nightmare. Teachers will have created hundreds, if not thousands, of Google Classrooms throughout the district. If these classes are not archived, students’ dashboards become cluttered with old assignments, and the school’s overall Google Workspace environment becomes disorganized.
Asking teachers to manually click into each of their classes and select “Archive” is rarely successful. Doing it manually as a Google Workspace Super Admin via the web console is incredibly tedious and time-consuming.
The most efficient and professional solution is to automate this process entirely using the Google Classroom API. By writing a simple script, you can command Google’s servers to automatically scan the entire district, identify every active class created before a specific date, and instantly move them to the Archive state.
Prerequisites for API Usage
Before you begin, you must have the following configured:
- You must be a Google Workspace Super Admin for your domain.
- You need a Google Cloud Platform (GCP) project with the Google Classroom API enabled.
- Authentication credentials (like a Service Account with Domain-Wide Delegation) configured in your script.
- A script written in Python, Node.js, or Google Apps Script. (We will look at the core API endpoint logic below, which applies to any language).
Step 1: Identifying the Target Courses
You cannot simply tell the API to “Archive everything.” You must first retrieve a list of the specific courses you want to target.
You achieve this by making an HTTP GET request to the courses list endpoint:
GET https://classroom.googleapis.com/v1/courses
To narrow down the massive list, you must append query parameters. The most important parameter is courseStates. You only want to retrieve courses that are currently ACTIVE (there is no point in trying to archive a course that is already archived).
GET https://classroom.googleapis.com/v1/courses?courseStates=ACTIVE
The API will return a massive JSON response containing an array of Course objects. Your script will need to iterate through this array. For each course, your code should look at the creationTime string. If the creation time is older than your cutoff date (e.g., older than July 1st of the previous year), you extract the unique id of that specific course to pass to the next step.
Step 2: Formatting the Archive Request
Once your script has identified the id of a course that needs to be archived (e.g., 1234567890), you must send a command to change its state.
Archiving a course is considered an update to the course object. Therefore, you must make an HTTP PATCH request to the specific course endpoint:
PATCH https://classroom.googleapis.com/v1/courses/1234567890?updateMask=courseState
Crucial Detail: Notice the updateMask=courseState parameter in the URL. If you do not include this, the API will reject the request. The updateMask tells the Google servers exactly which field in the massive course object you intend to modify, protecting against accidental data deletion.
The JSON body of your request is very simple. You just specify the new state:
{
"courseState": "ARCHIVED"
}Step 3: Handling Rate Limits in Your Script
When you send that PATCH request, the specific Google Classroom instantly disappears from the students’ active dashboards and is safely tucked away in the Archive section.
However, if you are archiving 5,000 courses across a school district, your script will be sending 5,000 rapid-fire PATCH requests to Google’s servers. Google APIs enforce strict “rate limits” (a maximum number of requests per second) to prevent DDoS attacks.
If your script blasts 5,000 requests in three seconds, Google will block your script and return HTTP 429 (Too Many Requests) errors.
When writing your script (whether in Python using time.sleep() or JavaScript), you must implement Exponential Backoff. This means if your script receives a 429 error, it should pause for 1 second and try again. If it fails again, it should pause for 2 seconds, then 4 seconds, etc.
Automating with Google Apps Script
If you don’t want to manage Python environments and OAuth tokens, the absolute easiest way to deploy this is using Google Apps Script.
Because Apps Script runs natively inside your Google Workspace, authentication is handled automatically. Furthermore, Google provides an Advanced Service wrapper for the Classroom API. Instead of formatting raw HTTP requests, you can archive a course with a single line of JavaScript:
Classroom.Courses.patch({courseState: "ARCHIVED"}, courseId, {updateMask: "courseState"});
By placing this code inside a loop that iterates through your active courses, you can automate your district’s entire end-of-year cleanup process with just a dozen lines of code.