Viewing asset history

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

1. 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.

   Enable the Cloud Asset Inventory API

2. Install the Google Cloud CLI on your local client.

REST

1. Confirm that you have access to the curl command.

2. 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 maximum time range is 7 days. 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 maximum time range is 7 days. 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:

  1. Go to the Google Cloud console.

     Go to the Google Cloud console

  2. Click the switcher box in the menu bar.
  3. Click the Select from box, and then select your organization.
  4. 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 maximum time range is 7 days. 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 maximum time range is 7 days. 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

Note: This is a GET method. However, the server doesn't accept a body for GET methods and the request URL is also length limited. To avoid errors, use a POST instead, and set a header of X-HTTP-Method-Override: GET.

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 maximum time range is 7 days. 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 maximum time range is 7 days. 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:

    1. Go to the Dashboard page in the Google Cloud console.

       Go to Dashboard

    2. Click the switcher box in the menu bar.
    3. Select your organization from the Select from box, and then search for your project name.
    4. 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:

    1. Go to the Google Cloud console.

       Go to the Google Cloud console

    2. Click the switcher box in the menu bar.
    3. Click the Select from box, and then select your organization.
    4. 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 maximum time range is 7 days. 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 maximum time range is 7 days. 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:

  1. Go to the Google Cloud console.

     Go to the Google Cloud console

  2. Click the switcher box in the menu bar.
  3. Click the Select from box, and then select your organization.
  4. 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 maximum time range is 7 days. 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 maximum time range is 7 days. 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

Note: This is a GET method. However, the server doesn't accept a body for GET methods and the request URL is also length limited. To avoid errors, use a POST instead, and set a header of X-HTTP-Method-Override: GET.

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 maximum time range is 7 days. 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 maximum time range is 7 days. 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:

    1. Go to the Dashboard page in the Google Cloud console.

       Go to Dashboard

    2. Click the switcher box in the menu bar.
    3. Select your organization from the Select from box, and then search for your project name.
    4. 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:

    1. Go to the Dashboard page in the Google Cloud console.

       Go to Dashboard

    2. Click the switcher box in the menu bar.
    3. Select your organization from the Select from box, and then search for your project name.
    4. 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:

    1. Go to the Google Cloud console.

       Go to the Google Cloud console

    2. Click the switcher box in the menu bar.
    3. Click the Select from box, and then select your organization.
    4. 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

Note: To use relationship types, you must subscribe to Security Command Center at the Premium tier.

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 maximum time range is 7 days. 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 maximum time range is 7 days. 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:

  1. Go to the Google Cloud console.

     Go to the Google Cloud console

  2. Click the switcher box in the menu bar.
  3. Click the Select from box, and then select your organization.
  4. 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 maximum time range is 7 days. 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 maximum time range is 7 days. 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

Note: This is a GET method. However, the server doesn't accept a body for GET methods and the request URL is also length limited. To avoid errors, use a POST instead, and set a header of X-HTTP-Method-Override: GET.

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 maximum time range is 7 days. 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 maximum time range is 7 days. 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:

    1. Go to the Dashboard page in the Google Cloud console.

       Go to Dashboard

    2. Click the switcher box in the menu bar.
    3. Select your organization from the Select from box, and then search for your project name.
    4. 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:

    1. Go to the Google Cloud console.

       Go to the Google Cloud console

    2. Click the switcher box in the menu bar.
    3. Click the Select from box, and then select your organization.
    4. 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

Note: To use relationship types, you must subscribe to Security Command Center at the Premium tier.

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 maximum time range is 7 days. 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 maximum time range is 7 days. 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:

  1. Go to the Google Cloud console.

     Go to the Google Cloud console

  2. Click the switcher box in the menu bar.
  3. Click the Select from box, and then select your organization.
  4. 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 maximum time range is 7 days. 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 maximum time range is 7 days. 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

Note: This is a GET method. However, the server doesn't accept a body for GET methods and the request URL is also length limited. To avoid errors, use a POST instead, and set a header of X-HTTP-Method-Override: GET.

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 maximum time range is 7 days. 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 maximum time range is 7 days. 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:

    1. Go to the Dashboard page in the Google Cloud console.

       Go to Dashboard

    2. Click the switcher box in the menu bar.
    3. Select your organization from the Select from box, and then search for your project name.
    4. 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:

    1. Go to the Google Cloud console.

       Go to the Google Cloud console

    2. Click the switcher box in the menu bar.
    3. Click the Select from box, and then select your organization.
    4. 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))"