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

gcloud

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.

API

1. Install oauth2l on your local machine for interacting with the Google OAuth system.
2. Confirm that you have access to the Unix curl command.
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 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.

Set Token Var

To get the access token, run the following command with the ~/credentials.json file.

oauth2l header --json ~/credentials.json cloud-platform

You should see an output similar to the following, with y29.xxxxxx as the access token:

Authorization: Bearer y29.xxxxxxx

Set the Token var to the access token:

Token=y29.xxxxxxx

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. Note that pageToken is different from Token mentioned above.

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
curl -X POST  -H "X-HTTP-Method-Override: GET" \
     -H "Authorization: Bearer $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 $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. Note that pageToken is different from Token mentioned above.

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
curl -X POST  -H "X-HTTP-Method-Override: GET" \
     -H "Authorization: Bearer $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 $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. Note that pageToken is different from Token mentioned above.

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
curl -X POST  -H "X-HTTP-Method-Override: GET" \
     -H "Authorization: Bearer $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 $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. Note that pageToken is different from Token mentioned above.

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
curl -X POST  -H "X-HTTP-Method-Override: GET" \
     -H "Authorization: Bearer $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. Note that pageToken is different from Token mentioned above.

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
curl -X POST  -H "X-HTTP-Method-Override: GET" \
     -H "Authorization: Bearer $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