> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracecat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Workspace Reports

> Reference for the Tracecat Google Workspace Reports integration: registered actions, required secrets, expected inputs, and example workflow usage.

## Get customer usage report

Action ID: `tools.google_reports.get_customer_usage_report`

Retrieves a report which is a collection of properties and statistics for a specific customer's account.

Reference: [https://developers.google.com/workspace/admin/reports/reference/rest/v1/customerUsageReports/get](https://developers.google.com/workspace/admin/reports/reference/rest/v1/customerUsageReports/get)

### Secrets

Optional secrets:

* `google_admin_oauth`: OAuth token `GOOGLE_ADMIN_USER_TOKEN`.
* `google_admin_oauth`: OAuth token `GOOGLE_ADMIN_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="date" type="string" required>
  Represents the date the usage occurred, based on UTC-8:00 (Pacific Standard Time). The timestamp is in the ISO 8601 format, `yyyy-mm-dd`.
</ParamField>

<ParamField path="customer_id" type="string | null">
  The unique ID of the customer to retrieve data for.

  Default: `null`.
</ParamField>

<ParamField path="page_token" type="string | null">
  Token to specify next page. A report with multiple pages has a `nextPageToken` property in the response.

  Default: `null`.
</ParamField>

<ParamField path="parameters" type="string | null">
  The `parameters` query string is a comma-separated list of event parameters that refine a report's results, in the form \{application name}:\{parameter name}. Applicable applications include `accounts`, `app_maker`, `apps_scripts`, `calendar`, `chat`, `classroom`, `cros`, `docs`, `gmail`, `gplus`, `device_management`, `meet` and `sites`.

  Default: `null`.
</ParamField>

## Get entity usage report

Action ID: `tools.google_reports.get_entity_usage_report`

Retrieves a report which is a collection of properties and statistics for entities used by users within the account.

Reference: [https://developers.google.com/workspace/admin/reports/reference/rest/v1/entityUsageReports/get](https://developers.google.com/workspace/admin/reports/reference/rest/v1/entityUsageReports/get)

### Secrets

Optional secrets:

* `google_admin_oauth`: OAuth token `GOOGLE_ADMIN_USER_TOKEN`.
* `google_admin_oauth`: OAuth token `GOOGLE_ADMIN_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="date" type="string" required>
  Represents the date the usage occurred, based on UTC-8:00 (Pacific Standard Time). The timestamp is in the ISO 8601 format, `yyyy-mm-dd`.
</ParamField>

<ParamField path="entity_key" type="string" required>
  Represents the key of the object to filter the data with. It is a string which can take the value `all` to get activity events for all users, or any other value for an app-specific entity.
</ParamField>

<ParamField path="entity_type" type="string" required>
  Represents the type of entity for the report. The only allowed value is `gplus_communities`, which returns a report on Google+ communities.
</ParamField>

<ParamField path="customer_id" type="string | null">
  The unique ID of the customer to retrieve data for.

  Default: `null`.
</ParamField>

<ParamField path="filters" type="string | null">
  The `filters` query string is a comma-separated list of an application's event parameters where the parameter's value is manipulated by a relational operator.

  Default: `null`.
</ParamField>

<ParamField path="max_results" type="integer | null">
  Determines how many activity records are shown on each response page. The default value is 1000, which is also the maximum.

  Default: `null`.
</ParamField>

<ParamField path="page_token" type="string | null">
  Token to specify next page. A report with multiple pages has a `nextPageToken` property in the response.

  Default: `null`.
</ParamField>

<ParamField path="parameters" type="string | null">
  The `parameters` query string is a comma-separated list of event parameters that refine a report's results, in the form \{application name}:\{parameter name}.

  Default: `null`.
</ParamField>

## Get user usage report

Action ID: `tools.google_reports.get_user_usage_report`

Retrieves a report which is a collection of properties and statistics for a set of users with the account.

Reference: [https://developers.google.com/workspace/admin/reports/reference/rest/v1/userUsageReport/get](https://developers.google.com/workspace/admin/reports/reference/rest/v1/userUsageReport/get)

### Secrets

Optional secrets:

* `google_admin_oauth`: OAuth token `GOOGLE_ADMIN_USER_TOKEN`.
* `google_admin_oauth`: OAuth token `GOOGLE_ADMIN_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="date" type="string" required>
  Represents the date the usage occurred, based on UTC-8:00 (Pacific Standard Time). The timestamp is in the ISO 8601 format, `yyyy-mm-dd`.
</ParamField>

<ParamField path="customer_id" type="string | null">
  The unique ID of the customer to retrieve data for.

  Default: `null`.
</ParamField>

<ParamField path="filters" type="string | null">
  The `filters` query string is a comma-separated list of an application's event parameters where the parameter's value is manipulated by a relational operator.

  Default: `null`.
</ParamField>

<ParamField path="group_id_filter" type="string | null">
  Comma separated group ids (obfuscated) on which user activities are filtered, i.e. the response will contain activities for only those users that are a part of at least one of the group ids mentioned here. Format: "id:abc123,id:xyz456".

  Default: `null`.
</ParamField>

<ParamField path="max_results" type="integer | null">
  Determines how many activity records are shown on each response page. The default value is 1000, which is also the maximum.

  Default: `null`.
</ParamField>

<ParamField path="org_unit_id" type="string | null">
  ID of the organizational unit to report on. User activity will be shown only for users who belong to the specified organizational unit.

  Default: `null`.
</ParamField>

<ParamField path="page_token" type="string | null">
  Token to specify next page. A report with multiple pages has a `nextPageToken` property in the response.

  Default: `null`.
</ParamField>

<ParamField path="parameters" type="string | null">
  The `parameters` query string is a comma-separated list of event parameters that refine a report's results, in the form \{application name}:\{parameter name}.

  Default: `null`.
</ParamField>

<ParamField path="user_key" type="string">
  Represents the profile ID or the user email for which the data should be filtered. Can be `all` for all information, or `userKey` for a user's unique Google Workspace profile ID or their primary email address. Must not be a deleted user.

  Default: `"all"`.
</ParamField>

## List activities

Action ID: `tools.google_reports.list_activities`

Retrieves a list of activities for a specific customer's account and application such as the Admin console application or the Google Drive application. Google is rolling out an audit log schema change that renames some event names and types, and after August 2026 only the updated names are returned; this action returns the events unchanged.

Reference: [https://developers.google.com/workspace/admin/reports/reference/rest/v1/activities/list](https://developers.google.com/workspace/admin/reports/reference/rest/v1/activities/list)

### Secrets

Optional secrets:

* `google_admin_oauth`: OAuth token `GOOGLE_ADMIN_USER_TOKEN`.
* `google_admin_oauth`: OAuth token `GOOGLE_ADMIN_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="application_name" type="string" required>
  Application name for which the events are to be retrieved. One of `access_transparency`, `admin`, `calendar`, `chat`, `drive`, `gcp`, `gmail`, `gplus`, `groups`, `groups_enterprise`, `jamboard`, `login`, `meet`, `mobile`, `rules`, `saml`, `token`, `user_accounts`, `context_aware_access`, `chrome`, `data_studio`, `keep`, `vault`, `gemini_in_workspace_apps`, `classroom`, `assignments`, `cloud_search`, `tasks`, `data_migration`, `meet_hardware`, `directory_sync`, `ldap`, `profile`, `access_evaluation`, `admin_data_action`, `contacts`, `takeout`, `graduation`.
</ParamField>

<ParamField path="actor_ip_address" type="string | null">
  The Internet Protocol (IP) Address of host where the event was performed. This parameter supports both IPv4 and IPv6 address versions.

  Default: `null`.
</ParamField>

<ParamField path="customer_id" type="string | null">
  The unique ID of the customer to retrieve data for.

  Default: `null`.
</ParamField>

<ParamField path="end_time" type="string | null">
  Sets the end of the range of time shown in the report. The date is in the RFC 3339 format, for example 2010-10-28T10:26:35.000Z. The default value is the approximate time of the API request. For Gmail requests, `startTime` and `endTime` must be provided and the difference must not be greater than 30 days.

  Default: `null`.
</ParamField>

<ParamField path="event_name" type="string | null">
  The name of the event being queried by the API. Each `eventName` is related to a specific Google Workspace service or feature which the API organizes into types of events.

  Default: `null`.
</ParamField>

<ParamField path="filters" type="string | null">
  Comma-separated list composed of event parameters manipulated by relational operators, in the form \{parameter1 name}\{relational operator}\{parameter1 value},... These event parameters are associated with a specific `eventName`. Supported relational operators are `==`, `&lt;>`, `&lt;`, `&lt;=`, `>` and `>=`.

  Default: `null`.
</ParamField>

<ParamField path="group_id_filter" type="string | null">
  Comma separated group ids (obfuscated) on which user activities are filtered, i.e. the response will contain activities for only those users that are a part of at least one of the group ids mentioned here. Format: "id:abc123,id:xyz456". To filter by groups, you must explicitly add the groups to your filtering groups allowlist.

  Default: `null`.
</ParamField>

<ParamField path="max_results" type="integer | null">
  Determines how many activity records are shown on each response page. The default value is 1000, which is also the maximum.

  Default: `null`.
</ParamField>

<ParamField path="org_unit_id" type="string | null">
  ID of the organizational unit to report on. Activity records will be shown only for users who belong to the specified organizational unit. Data before Dec 17, 2018 doesn't appear in the filtered results.

  Default: `null`.
</ParamField>

<ParamField path="page_token" type="string | null">
  The token to specify next page. A report with multiple pages has a `nextPageToken` property in the response.

  Default: `null`.
</ParamField>

<ParamField path="start_time" type="string | null">
  Sets the beginning of the range of time shown in the report. The date is in the RFC 3339 format, for example 2010-10-28T10:26:35.000Z. The `startTime` must be before the `endTime` (if specified) and the current time when the request is made. For Gmail requests, `startTime` and `endTime` must be provided and the difference must not be greater than 30 days.

  Default: `null`.
</ParamField>

<ParamField path="user_key" type="string">
  Represents the profile ID or the user email for which the data should be filtered. Can be `all` for all information, or `userKey` for a user's unique Google Workspace profile ID or their primary email address. Must not be a deleted user.

  Default: `"all"`.
</ParamField>