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.

Note: Listing assets might not meet the performance requirements for large scale customers. If this is the case for you and calling list API encounters timeout, it's recommended to use export API instead.

Before you begin

1. 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'll be running Cloud Asset API commands from.
   Enable the Cloud Asset Inventory API
2. Install the Google Cloud CLI on your local client.
3. 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. Below is the required permission for each ContentType in the request:

• CONTENT_TYPE_UNSPECIFIED: cloudasset.assets.listResource
• RESOURCE: cloudasset.assets.listResource
• IAM_POLICY: cloudasset.assets.listIamPolicy
• ORG_POLICY: cloudasset.assets.listOrgPolicy
• ACCESS_POLICY: cloudasset.assets.listAccessPolicy
• OS_INVENTORY: cloudasset.assets.listOSInventories
• RELATIONSHIP: 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 the assets in a project within a given timeframe using the Cloud Asset API, follow the steps below.

gcloud

The commands shown in this section list assets in a project. To list assets in an organization, use the --organization=ORGANIZATION_ID flag in your command.

The following example lists assets within a project.

Note that the earliest possible snapshot-time is the current time minus 35 days.

1. Ensure that you can call the Cloud Asset API by going through the Configure an account step.
2. Determine the resource types of the assets you want to list. This is the asset-types variable in the examples below.
3. Determine the content type you want to list. This is the content-type variable in the examples below.
4. Determine the time you want to list the assets at. This is the snapshot-time in the gcloud command, in RFC 3339 UTC format.

Note that you can specify the billing project with the flag --billing-project, which is the project you use to send the request. You can specify the target project you want to list with flag --project when you are listing assets from a project, or specify the target organization with flag --organization, or specify the target folder with flag --folder.

To see a full list of flags and options, run gcloud asset list --help.

List the assets in a project, including all resource metadata:

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
gcloud asset list --project='PROJECT_ID' \
  --billing-project='BILLING_PROJECT_ID' \
  --asset-types='compute.googleapis.com/Instance' \
  --snapshot-time=$NOW \
  --content-type='resource'

List the assets in a project, without resource metadata:

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
gcloud asset list --project='PROJECT_ID' \
  --billing-project='BILLING_PROJECT_ID' \
  --asset-types='compute.googleapis.com/Instance' \
  --snapshot-time=$NOW

List the assets in an organization, including all resource metadata:

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
gcloud asset list --organization='ORGANIZATION_NUMBER' \
  --billing-project='BILLING_PROJECT_ID' \
  --asset-types='compute.googleapis.com/Instance' \
  --snapshot-time=$NOW \
  --content-type='resource'

List the assets in an organization, without resource metadata:

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
gcloud asset list --organization='ORGANIZATION_NUMBER' \
  --billing-project='BILLING_PROJECT_ID' \
  --asset-types='compute.googleapis.com/Instance' \
  --snapshot-time=$NOW

List the assets in a folder, including all resource metadata:

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
gcloud asset list --folder='FOLDER_NUMBER' \
  --billing-project='BILLING_PROJECT_ID' \
  --asset-types='compute.googleapis.com/Instance' \
  --snapshot-time=$NOW \
  --content-type='resource'

List the assets in a folder, without resource metadata:

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
gcloud asset list --folder='FOLDER_NUMBER' \
  --billing-project='BILLING_PROJECT_ID' \
  --asset-types='compute.googleapis.com/Instance' \
  --snapshot-time=$NOW

List all relationships in a project:

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
gcloud asset list --folder='FOLDER_NUMBER' \
  --billing-project='BILLING_PROJECT_ID' \
  --asset-types='compute.googleapis.com/Instance' \
  --snapshot-time=$NOW \
  --content-type='relationship'

List specified relationships in a project:

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
gcloud asset list --folder='FOLDER_NUMBER' \
  --billing-project='BILLING_PROJECT_ID' \
  --content-type='relationship'\
  --relationship-types='INSTANCE_TO_INSTANCEGROUP'\
  --snapshot-time=$NOW

API

The commands shown in this section list assets of a project, organization, or folder.

1. Ensure that you can call the Cloud Asset API by going through the Configure an account step.
2. Determine the time you want to list the assets at. This is the readTime parameter in the following command, in RFC 3339 UTC format.
3. Determine the resource types of the asset you want to list. The following example uses compute.googleapis.com/Instance.
4. Determine the content type you want to list. This is the contentType variable in the examples below.

These examples use Application Default Credentials to authenticate to the Cloud Asset API.

List assets in a project, including all resource metadata

The pageToken parameter must not be set for the first page, and must be set to the page token value in response of previous page request.

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
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": "compute.googleapis.com/Instance", \
          "readTime": "'$NOW'", \
          "pageToken": "PAGE_TOKEN_FROM_PREVIOUS_PAGE_RESPONSE"}' \
     https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/assets

List assets in a project, without resource metadata

The pageToken parameter must not be set for the first page, and must be set to the page token value in response of previous page request.

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
curl -X POST  -H "X-HTTP-Method-Override: GET" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{"assetTypes": "compute.googleapis.com/Instance", \
          "readTime": "'$NOW'", \
          "pageToken": "PAGE_TOKEN_FROM_PREVIOUS_PAGE_RESPONSE"}' \
     https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/assets

List assets in an organization, including all resource metadata

The pageToken parameter must not be set for the first page, and must be set to the page token value in response of previous page request.

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
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": "compute.googleapis.com/Instance", \
          "readTime": "'$NOW'", \
          "pageToken": "PAGE_TOKEN_FROM_PREVIOUS_PAGE_RESPONSE"}' \
     https://cloudasset.googleapis.com/v1/organizations/ORGANIZATION_NUMBER/assets

List assets in an organization, without resource metadata

The pageToken parameter must not be set for the first page, and must be set to the page token value in response of previous page request.

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
curl -X POST  -H "X-HTTP-Method-Override: GET" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{"assetTypes": "compute.googleapis.com/Instance", \
          "readTime": "'$NOW'", \
          "pageToken": "PAGE_TOKEN_FROM_PREVIOUS_PAGE_RESPONSE"}' \
     https://cloudasset.googleapis.com/v1/ogranizations/ORGANIZATION_NUMBER/assets

List assets in a folder, including all resource metadata

The pageToken parameter must not be set for the first page, and must be set to the page token value in response of previous page request.

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
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": "compute.googleapis.com/Instance", \
          "readTime": "'$NOW'", \
          "pageToken": "PAGE_TOKEN_FROM_PREVIOUS_PAGE_RESPONSE"}' \
     https://cloudasset.googleapis.com/v1/folders/FOLDER_NUMBER/assets

List assets in a folder, without resource metadata

The pageToken parameter must not be set for the first page, and must be set to the page token value in response of previous page request.

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
curl -X POST  -H "X-HTTP-Method-Override: GET" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{"assetTypes": "compute.googleapis.com/Instance", \
          "readTime": "'$NOW'", \
          "pageToken": "PAGE_TOKEN_FROM_PREVIOUS_PAGE_RESPONSE"}' \
     https://cloudasset.googleapis.com/v1/folders/FOLDER_NUMBER/assets

List all relationships in a project

The pageToken parameter must not be set for the first page, and must be set to the page token value in response of previous page request.

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
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", \
          "assetTypes": "compute.googleapis.com/Instance", \
          "readTime": "'$NOW'", \
          "pageToken": "PAGE_TOKEN_FROM_PREVIOUS_PAGE_RESPONSE"}' \
     https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/assets

List specified relationships in a project

The pageToken parameter must not be set for the first page, and must be set to the page token value in response of previous page request.

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
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": "'$NOW'", \
          "pageToken": "PAGE_TOKEN_FROM_PREVIOUS_PAGE_RESPONSE"}' \
     https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/assets

API reference

• REST reference
• RPC reference