Listing assets

This page shows you how to use the Cloud Asset Inventory asset list service. You can use the Cloud Asset Inventory API to view a paginated list of the assets at a given timestamp.

Before you begin

Enable the Cloud Asset API before you can use the Google Cloud 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
Install the Google Cloud CLI on your local client.
Ensure that your account has one of the following roles on your project or organization of which you are going to list assets.
- roles/cloudasset.viewer
- roles/cloudasset.owner

Configure an account

To call the Cloud Asset API, your account must be granted the corresponding permission on the root (parent) resource, which is a project or organization that contains assets you want to list. Here is the required permission for each ContentType in the request:

Content type		Permission
gcloud name	REST name
`access-policy`	`ACCESS_POLICY`	`cloudasset.assets.listAccessPolicy`
`content-type-unspecified`	`CONTENT_TYPE_UNSPECIFIED`	`cloudasset.assets.listResource`
`iam-policy`	`IAM_POLICY`	`cloudasset.assets.listIamPolicy`
`org-policy`	`ORG_POLICY`	`cloudasset.assets.listOrgPolicy`
`os-inventory`	`OS_INVENTORY`	`cloudasset.assets.listOSInventories`
`relationship`	`RELATIONSHIP`	`cloudasset.assets.listResource`
`resource`	`RESOURCE`	`cloudasset.assets.listResource`

If your account has been granted the Cloud Asset Viewer (roles/cloudasset.viewer) role, or 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.

List assets

To list assets and their relationships in a project, folder, or organization at a given time using the Cloud Asset API, make one the following requests.

List assets in a project, folder, or organization, including all resource metadata

gcloud

Projects

gcloud asset list \
    --project=PROJECT_ID \
    --asset-types=ASSET_TYPE_1,ASSET_TYPE_2,... \
    --content-type=resource \
    --snapshot-time="SNAPSHOT_TIME"

Provide the following values:

PROJECT_ID: The ID of the project whose assets you want to list.
ASSET_TYPE: Optional. A comma-separated list of searchable asset types. RE2-compatible regular expressions are supported. If the regular expression does not match any supported asset type, an INVALID_ARGUMENT error is returned.
SNAPSHOT_TIME: Optional. The time at which you want to take a snapshot of your assets. The value must be the current time or a time no more than 35 days in the past. When not provided, a snapshot is taken at the current time. For information on time formats, see gcloud topic datetimes.

Remove the --content-type flag to exclude resource metadata.

Folders

List assets in a folder, including all resource metadata

gcloud asset list \
    --folder=FOLDER_ID \
    --asset-types=ASSET_TYPE_1,ASSET_TYPE_2,... \
    --content-type=resource \
    --snapshot-time="SNAPSHOT_TIME"

Provide the following values:

FOLDER_ID: The ID of the folder whose assets you want to list.
How to find a Google Cloud folder ID
Console

To find a Google Cloud folder ID, complete the following steps:

Go to the Google Cloud console.

Go to the Google Cloud console

Click the switcher box in the menu bar.

Click the Select from box, and then select your organization.

Search for your folder name. The folder ID is shown next to the folder name.
gcloud CLI

You can retrieve a Google Cloud folder ID that's located at the organization level with the following command:

gcloud resource-manager folders list \ --organization=$(gcloud organizations describe ORGANIZATION_NAME \ --format="value(name.segment(1))") \ --filter='"DISPLAY_NAME":"TOP_LEVEL_FOLDER_NAME"' \ --format="value(ID)"

Where TOP_LEVEL_FOLDER_NAME can be a full or partial string match. Remove the --format option to see further information about the found folders.

To get the ID of a folder within another folder, list the subfolders:

gcloud resource-manager folders list --folder=FOLDER_ID
ASSET_TYPE: Optional. A comma-separated list of searchable asset types. Regular expressions are supported. If the regular expression does not match any supported asset type, an INVALID_ARGUMENT error is returned.
SNAPSHOT_TIME: Optional. The time at which you want to take a snapshot of your assets. The value must be the current time or a time no more than 35 days in the past. When not provided, a snapshot is taken at the current time. For information on time formats, see gcloud topic datetimes.

Remove the --content-type flag to exclude resource metadata.

Organizations

List assets in an organization, including all resource metadata

gcloud asset list \
    --organization=ORGANIZATION_ID \
    --asset-types=ASSET_TYPE_1,ASSET_TYPE_2,... \
    --content-type=resource \
    --snapshot-time="SNAPSHOT_TIME"

Provide the following values:

ORGANIZATION_ID: The ID of the organization whose assets you want to list.
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.

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_TYPE: Optional. A comma-separated list of searchable asset types. Regular expressions are supported. If the regular expression does not match any supported asset type, an INVALID_ARGUMENT error is returned.
SNAPSHOT_TIME: Optional. The time at which you want to take a snapshot of your assets. The value must be the current time or a time no more than 35 days in the past. When not provided, a snapshot is taken at 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 '{
          "contentType": "RESOURCE",
          "assetTypes": [
            "ASSET_TYPE_1",
            "ASSET_TYPE_2",
            "..."
          ],
          "readTime": "SNAPSHOT_TIME",
          "pageToken": "PAGE_TOKEN"
         }' \
     https://cloudasset.googleapis.com/v1/SCOPE/assets

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_TYPE: Optional. An array of searchable asset types. Regular expressions are supported. If the regular expression does not match any supported asset type, an INVALID_ARGUMENT error is returned.
SNAPSHOT_TIME: Optional. The time at which you want to take a snapshot of your assets, 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, a snapshot is taken at the current time.
PAGE_TOKEN: Optional. Long request responses are separated over multiple pages. This key/value pair isn't required for the first page, however subsequent pages can be called by using the previous response's nextPageToken here.
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.
  
  Go to Dashboard
  
  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)"
- folders/FOLDER_ID
  How to find a Google Cloud folder ID
  Console
  
  To find a Google Cloud folder ID, complete the following steps:
  
  Go to the Google Cloud console.
  
  Go to the Google Cloud console
  
  Click the switcher box in the menu bar.
  
  Click the Select from box, and then select your organization.
  
  Search for your folder name. The folder ID is shown next to the folder name.
  
  gcloud CLI
  
  You can retrieve a Google Cloud folder ID that's located at the organization level with the following command:
  
  gcloud resource-manager folders list \ --organization=$(gcloud organizations describe ORGANIZATION_NAME \ --format="value(name.segment(1))") \ --filter='"DISPLAY_NAME":"TOP_LEVEL_FOLDER_NAME"' \ --format="value(ID)"
  
  Where TOP_LEVEL_FOLDER_NAME can be a full or partial string match. Remove the --format option to see further information about the found folders.
  
  To get the ID of a folder within another folder, list the subfolders:
  
  gcloud resource-manager folders list --folder=FOLDER_ID
- 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.
  
  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.

List specific relationships in a project, folder, or organization

gcloud

Projects

gcloud asset list \
    --project=PROJECT_ID \
    --content-type=relationship \
    --relationship-types=INSTANCE_TO_INSTANCEGROUP \
    --snapshot-time="SNAPSHOT_TIME"

Provide the following values:

PROJECT_ID: The ID of the project whose assets you want to list.
SNAPSHOT_TIME: Optional. The time at which you want to take a snapshot of your assets. The value must be the current time or a time no more than 35 days in the past. When not provided, a snapshot is taken at the current time. For information on time formats, see gcloud topic datetimes.

Remove the --relationship-types flag to list all relationships in a project.

Folders

gcloud asset list \
    --folder=FOLDER_ID \
    --content-type=relationship \
    --relationship-types=INSTANCE_TO_INSTANCEGROUP \
    --snapshot-time="SNAPSHOT_TIME"

Provide the following values:

FOLDER_ID: The ID of the folder whose assets you want to list.
How to find a Google Cloud folder ID
Console

To find a Google Cloud folder ID, complete the following steps:

Go to the Google Cloud console.

Go to the Google Cloud console

Click the switcher box in the menu bar.

Click the Select from box, and then select your organization.

Search for your folder name. The folder ID is shown next to the folder name.
gcloud CLI

You can retrieve a Google Cloud folder ID that's located at the organization level with the following command:

gcloud resource-manager folders list \ --organization=$(gcloud organizations describe ORGANIZATION_NAME \ --format="value(name.segment(1))") \ --filter='"DISPLAY_NAME":"TOP_LEVEL_FOLDER_NAME"' \ --format="value(ID)"

Where TOP_LEVEL_FOLDER_NAME can be a full or partial string match. Remove the --format option to see further information about the found folders.

To get the ID of a folder within another folder, list the subfolders:

gcloud resource-manager folders list --folder=FOLDER_ID
SNAPSHOT_TIME: Optional. The time at which you want to take a snapshot of your assets. The value must be the current time or a time no more than 35 days in the past. When not provided, a snapshot is taken at the current time. For information on time formats, see gcloud topic datetimes.

Remove the --relationship-types flag to list all relationships in a folder.

Organizations

gcloud asset list \
    --organization=ORGANIZATION_ID \
    --content-type=relationship \
    --relationship-types=INSTANCE_TO_INSTANCEGROUP \
    --snapshot-time="SNAPSHOT_TIME"

Provide the following values:

ORGANIZATION_ID: The ID of the organization whose assets you want to list.
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.

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))"
SNAPSHOT_TIME: Optional. The time at which you want to take a snapshot of your assets. The value must be the current time or a time no more than 35 days in the past. When not provided, a snapshot is taken at the current time. For information on time formats, see gcloud topic datetimes.

Remove the --relationship-types flag to list all relationships in an organization.

REST

curl -X POST \
     -H "X-HTTP-Method-Override: GET" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
          "contentType": "RELATIONSHIP",
          "relationshipTypes": "INSTANCE_TO_INSTANCEGROUP",
          "readTime": "SNAPSHOT_TIME",
          "pageToken": "PAGE_TOKEN"
         }' \
     https://cloudasset.googleapis.com/v1/SCOPE/assets

Provide the following values:

SNAPSHOT_TIME: Optional. The time at which you want to take a snapshot of your assets, 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, a snapshot is taken at the current time.
PAGE_TOKEN: Optional. Long request responses are separated over multiple pages. This key/value pair isn't required for the first page, however subsequent pages can be called by using the previous response's nextPageToken here.
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.
  
  Go to Dashboard
  
  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)"
- folders/FOLDER_ID
  How to find a Google Cloud folder ID
  Console
  
  To find a Google Cloud folder ID, complete the following steps:
  
  Go to the Google Cloud console.
  
  Go to the Google Cloud console
  
  Click the switcher box in the menu bar.
  
  Click the Select from box, and then select your organization.
  
  Search for your folder name. The folder ID is shown next to the folder name.
  
  gcloud CLI
  
  You can retrieve a Google Cloud folder ID that's located at the organization level with the following command:
  
  gcloud resource-manager folders list \ --organization=$(gcloud organizations describe ORGANIZATION_NAME \ --format="value(name.segment(1))") \ --filter='"DISPLAY_NAME":"TOP_LEVEL_FOLDER_NAME"' \ --format="value(ID)"
  
  Where TOP_LEVEL_FOLDER_NAME can be a full or partial string match. Remove the --format option to see further information about the found folders.
  
  To get the ID of a folder within another folder, list the subfolders:
  
  gcloud resource-manager folders list --folder=FOLDER_ID
- 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.
  
  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 relationshipTypes key/value pair to list all relationships in a project.

Listing assets

Before you begin

Configure an account

List assets

List assets in a project, folder, or organization, including all resource metadata

gcloud

Projects

Folders

List assets in a folder, including all resource metadata

Console

gcloud CLI

Organizations

List assets in an organization, including all resource metadata

Console

gcloud CLI

REST

Console

gcloud CLI

Console

gcloud CLI

Console

gcloud CLI

List specific relationships in a project, folder, or organization

gcloud

Projects

Folders

Console

gcloud CLI

Organizations

Console

gcloud CLI

REST

Console

gcloud CLI

Console

gcloud CLI

Console

gcloud CLI