Making Requests in the Drive Activity API

This guide explains how to make requests using the query method.

Query Key

There are two ways to request activity: by Drive item, or for everything underneath a folder hierarchy.

  • itemName: The format for this key is "items/ITEM_ID". Typically this is a file in Drive. If you specify a folder for this key, it will show activity for the folder itself, such as when the folder was created or renamed.

  • ancestorName: The format for this key is "items/FOLDER_ID", and the response will include activity on all items in the subtree underneath this folder.

When no key is set, it defaults to using an ancestor name of "items/root", which will show activity for all items in your Google Drive.

Pagination

The pageSize field allows you to request an approximate number of activities to return in each response. The actual count of returned activities will vary, so your app should handle arbitrary quantities in the response.

Page sizes are limited; if your app needs many activities, make multiple requests using pagination instead of setting a very large value for pageSize. Specifically, if there might be more activity to fetch than what was included in the response, then the response will also contain a nextPageToken. To retrieve more results, repeat the same request but add a pageToken field with the value of nextPageToken from the prior response.

Consolidation

Actions are often grouped together and returned together within a single DriveActivity. Some Action groupings occur spontaneously, such as moving an item into a shared folder triggering a permission change.

You can also specify a ConsolidationStrategy (sometimes called aggregation or batching) in the request. This will enable other groupings of related Actions, such as multiple Actors editing one item, or one actor moving multiple files into a new Drive folder.

While an individual Action has one Actor and one Target, after grouping, the resulting DriveActivity can have multiple Actors and multiple Targets. Even after grouping, however, there will always be a "primary" action which is either representative, or the most important, of all actions in the DriveActivity, depending on the requested consolidation strategy.

As a result, whether or not consolidation is enabled, it may be sufficient for many clients to look at only the top-level contents of a DriveActivity (i.e., the collective Actors andTargets with the primary ActionDetail) and ignore the detailed Actions in the response.

Filtering

You can restrict the actions which might be returned in the DriveActivity object by constructing a filter string in the request.

The restrict actions by time range, specify the field name time with numerical operators on date values either in terms of milliseconds since Jan 1, 1970 or in RFC 3339 format, such as:

  • time > 1452409200000 AND time <= 1492812924310
  • time >= "2016-01-10T01:02:03-05:00".

To restrict by action type, use the field name detail.action_detail_case with the "has" operator (:) and either a singular value or a list of allowed action types enclosed in parentheses. Examples include:

  • detail.action_detail_case: RENAME
  • detail.action_detail_case:(CREATE UPLOAD)
  • -detail.action_detail_case:MOVE

These filtering conditions can be combined within a single filter string.

Examples

Request 10 most recent activities for a Drive item:

{
  "item_name": "items/89ab67cd4523efghijklm1",
  "page_size": 10,
}

Request consolidated activities for every Drive item underneath an ancestor folder:

{
  "ancestor_name": "items/abc9999defgh",
  "consolidation_strategy": { "legacy": {} },
}

Request all Move and Rename actions on a Drive item:

{
  "item_name": "items/89ab67cd4523efghijklm1",
  "filter": "detail.action_detail_case:(MOVE RENAME)"
}

Request all activity since January 1, 2018 EST:

{
  "ancestor_name": "items/root",
  "filter": "time >= \"2018-01-01T00:00:00-05:00\""
}

Request all activity except Edits during June 2017 UTC:

{
  "ancestor_name": "items/root",
  "filter": "time >= \"2018-06-01T00:00:00Z\" time < \"2018-07-01T00:00:00Z\" -detail.action_detail_case:EDIT"
}

Send feedback about...

Google Drive Activity API
Need help? Visit our support page.