This page explains how to view the history of assets. The Cloud Asset API allows you to view the event change history of multiple assets whose time window overlaps with a given timeframe in the past 35 days. The event change history shows you all create, delete, and update events for the specified assets over time.
Before you begin
gcloud
You must enable the Cloud Asset API before you can use the gcloud CLI to access Cloud Asset Inventory. Note that the API only needs to be enabled on the project you're running Cloud Asset API commands from.
Install the Google Cloud CLI on your local client.
REST
Confirm that you have access to the
curl
command.Ensure that your account has been granted one of the following roles on your project, folder, or organization:
Cloud Asset Viewer (
roles/cloudasset.viewer
)Owner basic role (
roles/owner
)
Configure an account
Depending on the contentType
parameter of the API request, to call the Cloud Asset API, your account must be
granted a role that contains the following permissions on the root/parent
resource (project or organization) that contains assets you want to get history
for:
cloudasset.assets.exportResource
(for both Resource and Relationship)cloudasset.assets.exportIamPolicy
cloudasset.assets.exportOrgPolicy
cloudasset.assets.exportAccessPolicy
If your account has been granted the Cloud Asset Viewer
(roles/cloudasset.viewer
) role, the Cloud Asset Owner
(roles/cloudasset.owner
) role, or the Owner (roles/owner
) basic role on the
resource root, it already has sufficient permissions to call Cloud Asset API.
Otherwise, follow the steps on the Configuring Permissions
page.
Getting asset history
The following examples demonstrate how to get the create, delete, and update history of assets in a specified time window. Getting the history of assets in a folder isn't supported.
Get the history of specific assets in a project, including all resource metadata
gcloud
Projects
gcloud asset get-history \
--project=PROJECT_ID \
--asset-names=ASSET_NAME_1,ASSET_NAME_2,... \
--content-type=resource \
--start-time="START_TIME" \
--end-time="END_TIME"
Provide the following values:
PROJECT_ID
: The ID of the project whose assets you want the history for.ASSET_NAME
: A comma-separated list of asset full names you want the history for.START_TIME
: The beginning of the time range. The value must be the current time or a time no more than 35 days in the past. For information on time formats, see gcloud topic datetimes.END_TIME
: Optional. The finishing point of the time range. The value must be the current time or a time no more than 35 days in the past. When not provided, the end time is assumed to be the current time. For information on time formats, see gcloud topic datetimes.
Remove the --content-type
flag to exclude resource metadata.
Organizations
gcloud asset get-history \
--organization=ORGANIZATION_ID \
--asset-names=ASSET_NAME_1,ASSET_NAME_2,... \
--content-type=resource \
--start-time="START_TIME" \
--end-time="END_TIME"
Provide the following values:
ORGANIZATION_ID
: The ID of the organization whose assets you want the history for.How to find a Google Cloud organization ID
Console
To find a Google Cloud organization ID, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher box in the menu bar.
- Click the Select from box, and then select your organization.
- Click the All tab. The organization ID is shown next to the organization name.
gcloud CLI
You can retrieve a Google Cloud organization ID with the following command:
gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
-
ASSET_NAME
: A comma-separated list of asset full names you want the history for.START_TIME
: The beginning of the time range. The value must be the current time or a time no more than 35 days in the past. For information on time formats, see gcloud topic datetimes.END_TIME
: Optional. The finishing point of the time range. The value must be the current time or a time no more than 35 days in the past. When not provided, the end time is assumed to be the current time. For information on time formats, see gcloud topic datetimes.
Remove the --content-type
flag to exclude resource metadata.
REST
curl -X POST \
-H "X-HTTP-Method-Override: GET" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"assetNames": [
"ASSET_NAME_1",
"ASSET_NAME_2",
"..."
],
"contentType": "RESOURCE",
"readTimeWindow": {
"startTime": "START_TIME",
"endTime": "END_TIME"
}
}' \
https://cloudasset.googleapis.com/v1/SCOPE:batchGetAssetsHistory
Provide the following values:
ASSET_NAME
: A comma-separated list of asset full names you want the history for.START_TIME
: Optional. The beginning of the time range, in RFC 3339 format. The value must be the current time or a time no more than 35 days in the past.END_TIME
: Optional. The finishing point of the time range, in RFC 3339 format. The value must be the current time or a time no more than 35 days in the past. When not provided, the end time is assumed to be the current time.SCOPE
: A scope can be a project, a folder, or an organization.The allowed values are:
projects/PROJECT_ID
projects/PROJECT_NUMBER
How to find a Google Cloud project number
Console
To find a Google Cloud project number, complete the following steps:
-
Go to the Dashboard page in the Google Cloud console.
- Click the switcher box in the menu bar.
- Select your organization from the Select from box, and then search for your project name.
- Click the project name to switch to that project. The project number is shown in the Project info card.
gcloud CLI
You can retrieve a Google Cloud project number with the following command:
gcloud projects describe PROJECT_ID --format="value(projectNumber)"
-
organizations/ORGANIZATION_ID
How to find a Google Cloud organization ID
Console
To find a Google Cloud organization ID, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher box in the menu bar.
- Click the Select from box, and then select your organization.
- Click the All tab. The organization ID is shown next to the organization name.
gcloud CLI
You can retrieve a Google Cloud organization ID with the following command:
gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
-
Remove the contentType
key/value pair to exclude resource metadata.
Get the history of all IAM policies of specific assets in a project
gcloud
Projects
gcloud asset get-history \
--project=PROJECT_ID \
--asset-names=ASSET_NAME_1,ASSET_NAME_2,... \
--content-type=iam-policy \
--start-time="START_TIME" \
--end-time="END_TIME"
Provide the following values:
PROJECT_ID
: The ID of the project whose assets you want the history for.ASSET_NAME
: A comma-separated list of asset full names you want the history for.START_TIME
: The beginning of the time range. The value must be the current time or a time no more than 35 days in the past. For information on time formats, see gcloud topic datetimes.END_TIME
: Optional. The finishing point of the time range. The value must be the current time or a time no more than 35 days in the past. When not provided, the end time is assumed to be the current time. For information on time formats, see gcloud topic datetimes.
Organizations
gcloud asset get-history \
--organization=ORGANIZATION_ID \
--asset-names=ASSET_NAME_1,ASSET_NAME_2,... \
--content-type=iam-policy \
--start-time="START_TIME" \
--end-time="END_TIME"
Provide the following values:
ORGANIZATION_ID
: The ID of the organization whose assets you want the history for.How to find a Google Cloud organization ID
Console
To find a Google Cloud organization ID, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher box in the menu bar.
- Click the Select from box, and then select your organization.
- Click the All tab. The organization ID is shown next to the organization name.
gcloud CLI
You can retrieve a Google Cloud organization ID with the following command:
gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
-
ASSET_NAME
: A comma-separated list of asset full names you want the history for.START_TIME
: The beginning of the time range. The value must be the current time or a time no more than 35 days in the past. For information on time formats, see gcloud topic datetimes.END_TIME
: Optional. The finishing point of the time range. The value must be the current time or a time no more than 35 days in the past. When not provided, the end time is assumed to be the current time. For information on time formats, see gcloud topic datetimes.
REST
curl -X POST \
-H "X-HTTP-Method-Override: GET" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"assetNames": [
"ASSET_NAME_1",
"ASSET_NAME_2",
"..."
],
"contentType": "IAM_POLICY",
"readTimeWindow": {
"startTime": "START_TIME",
"endTime": "END_TIME"
}
}' \
https://cloudasset.googleapis.com/v1/SCOPE:batchGetAssetsHistory
Provide the following values:
ASSET_NAME
: A comma-separated list of asset full names you want the history for.START_TIME
: Optional. The beginning of the time range, in RFC 3339 format. The value must be the current time or a time no more than 35 days in the past.END_TIME
: Optional. The finishing point of the time range, in RFC 3339 format. The value must be the current time or a time no more than 35 days in the past. When not provided, the end time is assumed to be the current time.SCOPE
: A scope can be a project, a folder, or an organization.The allowed values are:
projects/PROJECT_ID
projects/PROJECT_NUMBER
How to find a Google Cloud project number
Console
To find a Google Cloud project number, complete the following steps:
-
Go to the Dashboard page in the Google Cloud console.
- Click the switcher box in the menu bar.
- Select your organization from the Select from box, and then search for your project name.
- Click the project name to switch to that project. The project number is shown in the Project info card.
gcloud CLI
You can retrieve a Google Cloud project number with the following command:
gcloud projects describe PROJECT_ID --format="value(projectNumber)"
-
projects/PROJECT_NUMBER
How to find a Google Cloud project number
Console
To find a Google Cloud project number, complete the following steps:
-
Go to the Dashboard page in the Google Cloud console.
- Click the switcher box in the menu bar.
- Select your organization from the Select from box, and then search for your project name.
- Click the project name to switch to that project. The project number is shown in the Project info card.
gcloud CLI
You can retrieve a Google Cloud project number with the following command:
gcloud projects describe PROJECT_ID --format="value(projectNumber)"
-
organizations/ORGANIZATION_ID
How to find a Google Cloud organization ID
Console
To find a Google Cloud organization ID, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher box in the menu bar.
- Click the Select from box, and then select your organization.
- Click the All tab. The organization ID is shown next to the organization name.
gcloud CLI
You can retrieve a Google Cloud organization ID with the following command:
gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
-
Get the history of all relationships of specific assets in a project
gcloud
Projects
gcloud asset get-history \
--project=PROJECT_ID \
--asset-names=ASSET_NAME_1,ASSET_NAME_2,... \
--content-type=relationship \
--start-time="START_TIME" \
--end-time="END_TIME"
Provide the following values:
PROJECT_ID
: The ID of the project whose assets you want the history for.ASSET_NAME
: A comma-separated list of asset full names you want the history for.START_TIME
: The beginning of the time range. The value must be the current time or a time no more than 35 days in the past. For information on time formats, see gcloud topic datetimes.END_TIME
: Optional. The finishing point of the time range. The value must be the current time or a time no more than 35 days in the past. When not provided, the end time is assumed to be the current time. For information on time formats, see gcloud topic datetimes.
Organizations
gcloud asset get-history \
--organization=ORGANIZATION_ID \
--asset-names=ASSET_NAME_1,ASSET_NAME_2,... \
--content-type=relationship \
--start-time="START_TIME" \
--end-time="END_TIME"
Provide the following values:
ORGANIZATION_ID
: The ID of the organization whose assets you want the history for.How to find a Google Cloud organization ID
Console
To find a Google Cloud organization ID, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher box in the menu bar.
- Click the Select from box, and then select your organization.
- Click the All tab. The organization ID is shown next to the organization name.
gcloud CLI
You can retrieve a Google Cloud organization ID with the following command:
gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
-
ASSET_NAME
A comma-separated list of asset full names you want the history for.START_TIME
: The beginning of the time range. The value must be the current time or a time no more than 35 days in the past. For information on time formats, see gcloud topic datetimes.END_TIME
: Optional. The finishing point of the time range. The value must be the current time or a time no more than 35 days in the past. When not provided, the end time is assumed to be the current time. For information on time formats, see gcloud topic datetimes.
REST
curl -X POST \
-H "X-HTTP-Method-Override: GET" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"assetNames": [
"ASSET_NAME_1",
"ASSET_NAME_2",
"..."
],
"contentType": "RELATIONSHIP",
"readTimeWindow": {
"startTime": "START_TIME",
"endTime": "END_TIME"
}
}' \
https://cloudasset.googleapis.com/v1/SCOPE:batchGetAssetsHistory
Provide the following values:
ASSET_NAME
: A comma-separated list of asset full names you want the history for.START_TIME
: Optional. The beginning of the time range, in RFC 3339 format. The value must be the current time or a time no more than 35 days in the past.END_TIME
: Optional. The finishing point of the time range, in RFC 3339 format. The value must be the current time or a time no more than 35 days in the past. When not provided, the end time is assumed to be the current time.SCOPE
: A scope can be a project, a folder, or an organization.The allowed values are:
projects/PROJECT_ID
projects/PROJECT_NUMBER
How to find a Google Cloud project number
Console
To find a Google Cloud project number, complete the following steps:
-
Go to the Dashboard page in the Google Cloud console.
- Click the switcher box in the menu bar.
- Select your organization from the Select from box, and then search for your project name.
- Click the project name to switch to that project. The project number is shown in the Project info card.
gcloud CLI
You can retrieve a Google Cloud project number with the following command:
gcloud projects describe PROJECT_ID --format="value(projectNumber)"
-
organizations/ORGANIZATION_ID
How to find a Google Cloud organization ID
Console
To find a Google Cloud organization ID, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher box in the menu bar.
- Click the Select from box, and then select your organization.
- Click the All tab. The organization ID is shown next to the organization name.
gcloud CLI
You can retrieve a Google Cloud organization ID with the following command:
gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
-
Get the history of specific relationships of specific assets in a project
gcloud
Projects
gcloud asset get-history \
--project=PROJECT_ID \
--asset-names=ASSET_NAME_1,ASSET_NAME_2,... \
--content-type=relationship \
--relationship-types=INSTANCE_TO_INSTANCEGROUP \
--start-time="START_TIME" \
--end-time="END_TIME"
Provide the following values:
PROJECT_ID
: The ID of the project whose assets you want the history for.ASSET_NAME
: A comma-separated list of asset full names you want the history for.START_TIME
: The beginning of the time range. The value must be the current time or a time no more than 35 days in the past. For information on time formats, see gcloud topic datetimes.END_TIME
: Optional. The finishing point of the time range. The value must be the current time or a time no more than 35 days in the past. When not provided, the end time is assumed to be the current time. For information on time formats, see gcloud topic datetimes.
Organizations
gcloud asset get-history \
--organization=ORGANIZATION_ID \
--asset-names=ASSET_NAME_1,ASSET_NAME_2,... \
--content-type=relationship \
--relationship-types=INSTANCE_TO_INSTANCEGROUP \
--start-time="START_TIME" \
--end-time="END_TIME"
Provide the following values:
ORGANIZATION_ID
: The ID of the organization whose assets you want the history for.How to find a Google Cloud organization ID
Console
To find a Google Cloud organization ID, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher box in the menu bar.
- Click the Select from box, and then select your organization.
- Click the All tab. The organization ID is shown next to the organization name.
gcloud CLI
You can retrieve a Google Cloud organization ID with the following command:
gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
-
ASSET_NAME
: A comma-separated list of asset full names you want the history for.START_TIME
: The beginning of the time range. The value must be the current time or a time no more than 35 days in the past. For information on time formats, see gcloud topic datetimes.END_TIME
: Optional. The finishing point of the time range. The value must be the current time or a time no more than 35 days in the past. When not provided, the end time is assumed to be the current time. For information on time formats, see gcloud topic datetimes.
REST
curl -X POST \
-H "X-HTTP-Method-Override: GET" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"assetNames": [
"ASSET_NAME_1",
"ASSET_NAME_2",
"..."
],
"contentType": "RELATIONSHIP",
"relationshipTypes": "INSTANCE_TO_INSTANCEGROUP",
"readTimeWindow": {
"startTime": "START_TIME",
"endTime": "END_TIME"
}
}' \
https://cloudasset.googleapis.com/v1/SCOPE:batchGetAssetsHistory
Provide the following values:
ASSET_NAME
: A comma-separated list of asset full names you want the history for.START_TIME
: Optional. The beginning of the time range, in RFC 3339 format. The value must be the current time or a time no more than 35 days in the past.END_TIME
: Optional. The finishing point of the time range, in RFC 3339 format. The value must be the current time or a time no more than 35 days in the past. When not provided, the end time is assumed to be the current time.SCOPE
: A scope can be a project, a folder, or an organization.The allowed values are:
projects/PROJECT_ID
projects/PROJECT_NUMBER
How to find a Google Cloud project number
Console
To find a Google Cloud project number, complete the following steps:
-
Go to the Dashboard page in the Google Cloud console.
- Click the switcher box in the menu bar.
- Select your organization from the Select from box, and then search for your project name.
- Click the project name to switch to that project. The project number is shown in the Project info card.
gcloud CLI
You can retrieve a Google Cloud project number with the following command:
gcloud projects describe PROJECT_ID --format="value(projectNumber)"
-
organizations/ORGANIZATION_ID
How to find a Google Cloud organization ID
Console
To find a Google Cloud organization ID, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher box in the menu bar.
- Click the Select from box, and then select your organization.
- Click the All tab. The organization ID is shown next to the organization name.
gcloud CLI
You can retrieve a Google Cloud organization ID with the following command:
gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
-