How to Use Google Workspace Drive API to Empty the Trash Automatically

In Google Workspace, when a user deletes a file, it isn’t actually deleted. It is moved to the Trash. While Google recently updated its policy to auto-delete items in the Trash after 30 days, 30 days is a long time if an employee accidentally dumps 500GB of 4K video files into their Trash, instantly maxing out their storage quota and breaking their ability to receive emails in Gmail. If you are a Workspace administrator managing thousands of users, you cannot manually log into their accounts to click “Empty Trash.” You need to automate this process using the Google Drive API.

Step 1: Understand Service Accounts and Impersonation

To empty the trash of a different user in your organization, your API script cannot run as “you” (the Admin). The script must use a Service Account configured with Domain-Wide Delegation. This allows the script to mathematically impersonate the user whose quota is full, authenticating as them without knowing their password.

When you build your Google API credentials object in Python or Node.js, you must explicitly set the subject parameter to the email address of the user you want to impersonate (e.g., [email protected]).

Step 2: The Old Way (Iterating and Deleting)

In older versions of the API, emptying the trash required a heavy script. You had to:

1. Use files().list() with the search query q="trashed=true".
2. Paginate through hundreds of results.
3. Execute a files().delete(fileId=X) API call for every single file.

If a user had 10,000 items in the trash, your script had to make 10,000 HTTP requests, taking a massive amount of time and potentially hitting Google’s rate limits.

Step 3: The Modern Way (files.emptyTrash)

Google eventually realized administrators needed a faster way and introduced a dedicated endpoint: files().emptyTrash(). This acts exactly like clicking the “Empty Trash” button in the web interface. It sends one single HTTP request to Google’s servers, and Google handles the bulk deletion asynchronously in the background.

Here is how you execute it using the official Python client library, assuming your service object is already authenticated and impersonating the target user:

try:
    # Execute the empty trash command
    service.files().emptyTrash().execute()
    print("Trash emptying process initiated successfully.")

except Exception as e:
    print(f"An error occurred: {e}")

Step 4: Handling Shared Drives

There is a critical caveat: The emptyTrash() method only applies to the user’s personal “My Drive.” It does not touch the trash in Shared Drives (formerly Team Drives).

If the 500GB of video files were deleted from a Shared Drive, emptying the user’s personal trash will not free up the organization’s pooled storage quota. Shared Drives have their own separate trash.

Currently, the Drive API does not have an emptyTrash equivalent for Shared Drives. To permanently delete items trashed in a Shared Drive via the API, you must fall back to the old method:

1. Query the files: q="trashed=true" and include driveId='THE_SHARED_DRIVE_ID', corpora='drive', and includeItemsFromAllDrives=True.
2. Iterate through the results.
3. Call service.files().delete(fileId=item['id']).execute() for each file.

Step 5: Automating the Quota Check

To build a fully automated system, you can combine the Drive API with the Admin SDK Directory API.

1. Use the Directory API to pull a list of all users and check their storage.quota.usageInMb.
2. If a user’s usage exceeds 95% of their limit, trigger the Drive API script.
3. Impersonate that user and execute emptyTrash().
4. Log the action and send an automated email to the user explaining that their trash was cleared to prevent a service interruption.

By automating trash management, you can keep your Google Workspace environment running smoothly without requiring emergency manual intervention from the helpdesk.