When interacting with the Google Drive API, downloading a file’s actual content (like the text of a document or the pixels of an image) is relatively rare. The vast majority of API calls involve managing the metadata of files—querying names, dates, owners, sharing permissions, and parent folders. To build efficient scripts (such as auditing tools to find outdated files or reports detailing who owns what), you must master how the Drive API handles metadata requests using the fields parameter.
The Problem with Default API Responses
A file in Google Drive has dozens of metadata attributes. However, if you make a basic request to get a file (e.g., GET https://www.googleapis.com/drive/v3/files/[FILE_ID]), the API does not return all of this information. By default, Google only returns four basic fields: id, name, mimeType, and kind.
If your script needs to know when the file was last modified, the default response will be useless. You must explicitly request the exact metadata you need.
Using the fields Parameter
To retrieve specific metadata, you append the fields query parameter to your API request. This is a comma-separated list of the exact attributes you want Google to return.
Commonly requested metadata fields include:
createdTime: When the file was made.modifiedTime: When it was last changed.owners: An array containing the email addresses of the file owners.size: The file size in bytes (only applies to binary files like PDFs, not Google Docs).parents: An array of the folder IDs containing the file.shared: A boolean indicating if the file has been shared.
Example using Python
Here is how you request specific metadata using the official Google API Client Library for Python.
# The ID of the file you want to query
file_id = '1aB2c3D4e5F6g7H8i9J0'
# Execute the API call, specifying the fields
file_metadata = service.files().get(
fileId=file_id,
fields='id, name, createdTime, modifiedTime, owners, size'
).execute()
print(f"File Name: {file_metadata.get('name')}")
print(f"Created: {file_metadata.get('createdTime')}")
print(f"Modified: {file_metadata.get('modifiedTime')}")
# Owners is a list of dictionaries, so we must loop or access index 0
owner_email = file_metadata.get('owners')[0].get('emailAddress')
print(f"Owner: {owner_email}")Handling the fields Parameter in List Requests
Querying a single file is simple. However, things get complicated when you use the files().list() method to search for multiple files. The list method returns a JSON object containing an array of files called files.
If you specify fields='name, modifiedTime' in a list request, the API will throw an error, because the top-level JSON object does not have a “name” property; the files inside the array do.
You must use nested syntax to tell the API to look inside the files array.
# Correctly formatting fields for a list request
results = service.files().list(
q="mimeType='application/pdf'",
pageSize=10,
fields="nextPageToken, files(id, name, modifiedTime, owners)"
).execute()
items = results.get('files', [])
for item in items:
print(f"{item['name']} - Last Modified: {item['modifiedTime']}")Notice the syntax files(id, name, modifiedTime). This instructs Google to return the file array, and for every object within that array, return only the ID, name, and modified time. Using the fields parameter effectively is the key to writing fast, bandwidth-efficient Google Drive applications.