How to Use Google Workspace Drive API to Generate Activity Reports

If you are an IT administrator for a large organization using Google Workspace, you cannot rely entirely on user trust. If an employee submits their two-week notice and suddenly downloads 5,000 internal documents to their local hard drive, or if someone accidentally changes the sharing permissions on a confidential HR spreadsheet to “Anyone with the link,” you need to know immediately. While the Google Admin Console provides a visual audit log, building automated security alerts or archiving compliance data requires interacting programmatically with the Google Workspace Reports API.

Understanding the Reports API

The Reports API (part of the broader Admin SDK) allows you to query the activity logs for various Google services, including Google Drive, Login events, and Admin console changes. It is fundamentally different from the standard Drive API; the Drive API interacts with files, while the Reports API interacts with the audit trail of those files.

To use this API, your Google Cloud Project must have the Admin SDK API enabled, and the authenticated user must be a Google Workspace Super Administrator (or a custom admin role with the “Reports” privilege).

Step 1: Authenticate the Script

Your Python script needs to request the specific OAuth scope required to read audit logs:

SCOPES = ['https://www.googleapis.com/auth/admin.reports.audit.readonly']

Using the official Google API Client Library for Python, you build the service object:

from googleapiclient.discovery import build

# Assuming credentials have been loaded via Service Account or OAuth
service = build('admin', 'reports_v1', credentials=creds)

Step 2: Querying Drive Activity

To pull the logs for Google Drive, you use the activities().list() method. You must specify the application name (drive) and the userKey (either a specific user’s email address or all for the entire organization).

results = service.activities().list(
    userKey='all',
    applicationName='drive',
    maxResults=50
).execute()

activities = results.get('items', [])

Step 3: Parsing the Event Data

The JSON response from the Reports API is dense and heavily nested. Every “activity” contains an actor (who did it), an id (when it happened), and a list of events (what exactly they did).

Here is how you parse the response to identify specific actions, such as when a user downloads a file or changes its permissions:

if not activities:
    print('No activity found.')
else:
    for activity in activities:
        # Who performed the action
        actor_email = activity['actor']['email']
        
        # Loop through the events in this activity
        for event in activity['events']:
            event_name = event['name']
            
            # Extract parameters (like file name or document ID)
            parameters = {param['name']: param.get('value', param.get('multiValue', '')) 
                          for param in event['parameters']}
            
            doc_title = parameters.get('doc_title', 'Unknown Document')
            
            # Look for specific security events
            if event_name == 'download':
                print(f"ALERT: {actor_email} downloaded '{doc_title}'")
                
            elif event_name == 'change_user_access':
                print(f"SECURITY: {actor_email} changed permissions on '{doc_title}'")

Step 4: Filtering with the eventName Parameter

If your organization has 10,000 employees, pulling all events and filtering them in Python is incredibly slow and inefficient. You can force Google’s servers to do the filtering for you by using the eventName parameter in your initial request.

To build a script that only looks for files being deleted (trashed):

results = service.activities().list(
    userKey='all',
    applicationName='drive',
    eventName='trash'
).execute()

Common Drive event names include:

• create, edit, view
• download (Useful for data exfiltration alerts)
• trash, untrash, delete
• change_user_access, change_document_visibility (Useful for detecting accidental public sharing)

Step 5: Building a Scheduled Alert System

A typical enterprise implementation involves writing a Python script that uses the startTime parameter to query the last 15 minutes of logs. The script is deployed to a server (like a cron job on an Ubuntu VM or an AWS Lambda function) and runs continuously. If it detects a spike in download events from a single user, it immediately sends a webhook alert to the IT department’s Slack or Microsoft Teams channel, enabling a rapid response to potential data theft.