The entities usage report returns Google Workspace service activities related to entities used by your account's users. These reports can be customized and filtered for specific usage information. Data is available for the past 30 days.
The entities usage report may be used only for lawful purposes in accordance with your Customer Agreement. These reports also apply to Google Workspace and Education.
Retrieve all entities usage activities
Currently, the only entity type supported by this API is Google+ communities. To retrieve a
report of all activities related to app entities in your account, use the following
GET HTTP request and include the authorization token described in the
authorization documentation. For
readability, the following example is formatted with line returns:
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/date ?parameters=applicationParameters &filters=parameterFilters &maxResults=maxResults
The date value is the date the usage occurred and the timestamp is in the ISO 8601 format, yyyy-mm-dd. We recommend you use your account's time zone for this. For more information about the query string parameters and response properties, see the API Reference. For information about the entities usage report parameters, see the Entities Usage Parameters reference.
applicationParameters is a comma-separated list of parameters you wish to retrieve.
Each parameter is formatted as application:parameter_name, for example,
gplus:community_name. The available parameters are documented in the
Entities Usage Parameters
reference. If no parameters are specified, all are returned.
parameterFilters is a comma-separated list of filters to apply to the results. Each
filter is formatted as
application:parameter_name[relational_operator]parameter_value. For example, the
filter gplus:num_total_members>100 filters the results to contain only results
where the gplus:num_total_members parameter has a value greater than 100.
maxResults is the maximum number of results to return in a single fetch. If the total
number of results is greater than this, the response will be truncated and a
nextPageToken will be included (see the
JSON response example below).
Examples
The following example gets a report containing all parameters
for all gplus_communities entities.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all /dates/2017-12-11
The following example gets a report containing the community_name parameter
for all gplus_communities entities.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all /dates/2017-12-11?parameters=gplus:community_name
The following example gets a report of community_name and
num_total_members for each gplus_communities entity, filtered by
communities with more than 100 members. For an example of an API response, see the
JSON response example.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/2017-12-11 ?parameters=gplus:community_name,gplus:num_total_members&filters=gplus:num_total_members>100
Retrieve a report for a specific entity
To retrieve a report for a specific entity, use the following GET HTTP request and
include the authorization token described in the
authorization documentation. For
readability, the following example is formatted with line returns.
GET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date ?parameters=applicationParameters &filters=parameterFilters &maxResults=maxResults
The entityKey is an entity identifier which is specific to the application where the entity lives. See the API Reference for details on how to obtain the entityKey for the particular entity you are interested in. The other parameters are documented above under Retrieve all entities usage activities.
For more information about the query string parameters and response properties, see the API Reference. For information about the entities usage report parameters, see the Entities Usage Parameters reference.
Examples
The following example gets the entity report for a gplus_community entity with the
entityKey "1234".
https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11
Usage report example JSON response
A successful response returns an HTTP 200 status code. Along with the status code, the response returns a report. Some of the parameters in the response have been omitted for readability.
Example JSON response for entities report
{
"kind": "reports#usageReports",
"nextPageToken": "NjQ1OTgwODk0MzkxNDAwNjQ0OA",
"usageReports": [
{
"kind": "admin#reports#usageReport",
"date": "2017-12-11",
"entity": {
"type": "OBJECT",
"customerId": "C03az79cb",
"objectType": "GPLUS_COMMUNITY",
"objectId": "1234",
},
"parameters": [
{
"name": "gplus:community_name",
"stringValue": "My Community"
},
{
"name": "gplus:num_total_members",
"intValue": 37
},
{
"name": "gplus:num_7day_active_members",
"intValue": 12
},
{
"name": "gplus:num_30day_active_members",
"intValue": 17
},
]
}
]
}
Example JSON response for entities report with warnings
One or more warnings may be returned in the response if the request cannot be fulfilled. In this example, the report is not available at the time the request is made.{
"kind": "reports#usageReports",
"warnings": [
{
"code": "PARTIAL_DATA_AVAILABLE"
"message": "Data for date 2017-12-11 for application gplus is not available right now, please try again after a few hours."
"data": [
{
"key": "date"
"value": "2017-12-11"
}
]
}
],
"usageReports": [],
}
Each entry in the warnings array has the following parameters:
code: machine-readable warning codemessage: human-readable warning messagedata: list of key-value pairs which give detailed warning information