Search for resources

You can search for resources in a project, folder, or organization, and filter the returned results using a query.

Before you begin

  1. Enable the Cloud Asset Inventory API in the project you're running Cloud Asset Inventory commands from.

    Enable the Cloud Asset Inventory API

  2. Make sure your account has the correct role to call the Cloud Asset Inventory API. For individual permissions for each call type, see Permissions.

Construct a query

Before constructing a query, it can be useful to start with a search request that doesn't specify a query. Use the fields and values from the full response to create a query using the search query syntax, and refine it until the results you want are returned.

Fields that can be used in a query are detailed in the searchAllResources reference documentation.

Not all resources can be searched. See Resource types for resource names and to check if they are available to the search APIs.

Search for your resources

Console

To search for resource metadata, complete the following steps.

  1. Go to the Asset Inventory page in the Google Cloud console.

    Go to Asset Inventory

  2. Change to the project, folder, or organization you want to search.
  3. Click the Resource tab.

  4. To search resources, enter a query in the Filter field. See Search query syntax to learn how to write a search query.

    To make constructing queries easier, you can click the Filter field to display and add the available searchable fields to your query.

After performing a search, the resources matching the query are listed in the Results table. Double-click your query to edit it, or use the Filter results pane to restrict the search results by specific criteria.

To view the query as a Google Cloud CLI command, click View query.

To export the results, click Download CSV.

gcloud

gcloud asset search-all-resources \
    --scope=SCOPE_PATH \
    --query="QUERY" \
    --asset-types=ASSET_TYPE_1,ASSET_TYPE_2,... \
    --order-by="ORDER_BY" \
    --read-mask="READ_MASK"

Provide the following values:

  • SCOPE_PATH: Use one of the following values:

    The allowed values are:

    • projects/PROJECT_ID, where PROJECT_ID is the ID of the project that has the assets you want to search for.

    • projects/PROJECT_NUMBER, where PROJECT_NUMBER is the number of the project that has the assets you want to search for.

      How to find a Google Cloud project number

      Google Cloud console

      To find a Google Cloud project number, complete the following steps:

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

        Go to Welcome

      2. Click the switcher list box in the menu bar.

      3. Select your organization from the list box, and then search for your project name. The project name, project number, and project ID are shown near the Welcome heading.

        Up to 4,000 resources are displayed. If you don't see the project you're looking for, go to the Manage resources page and filter the list using the name of that project.

      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, where FOLDER_ID is the ID of the folder that has the assets you want to search for.

      How to find the ID of a Google Cloud folder

      Google Cloud console

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

      1. Go to the Google Cloud console.

        Go to the Google Cloud console

      2. Click the switcher list box in the menu bar.
      3. Select your organization from the list box.
      4. Search for your folder name. The folder ID is shown next to the folder name.

      gcloud CLI

      You can retrieve the ID of a Google Cloud folder 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 is a partial or full string match for the folder's name. Remove the --format flag to see more information about the found folders.

      The previous command doesn't return the IDs of subfolders within folders. To do so, run the following command using a top level folder's ID:

      gcloud resource-manager folders list --folder=FOLDER_ID

    • organizations/ORGANIZATION_ID, where ORGANIZATION_ID is the ID of the organization that has the assets you want to search for.

      How to find the ID of a Google Cloud organization

      Google Cloud console

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

      1. Go to the Google Cloud console.

        Go to the Google Cloud console

      2. Click the switcher list box in the menu bar.
      3. Select your organization from the list box.
      4. Click the All tab. The organization ID is shown next to the organization name.

      gcloud CLI

      You can retrieve the ID of a Google Cloud organization with the following command:

      gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
  • QUERY: Optional. The query expression. If not specified or empty, all resources are searched for in the specified scope. To learn how to write a search query, see Search query syntax.
  • ASSET_TYPE_#: Optional. A comma-separated list of searchable asset types. RE2-compatible regular expressions are supported. If the regular expression doesn't match any supported asset type, an INVALID_ARGUMENT error is returned. When --asset-types isn't specified, all asset types are returned.
  • ORDER_BY: Optional. A comma-separated list of fields specifying the sorting order of the results. The default order is ascending. Add DESC after the field name to indicate descending order. See the reference documentation for what fields can be sorted.
  • READ_MASK: Optional. A comma-separated list of fields specifying which fields to be returned in the results. See the reference documentation for the fields that are returned by default, and other conditions to keep in mind when specifying a read mask.

You can use the --format and --flatten flags to format the gcloud CLI output.

See the gcloud CLI reference for all options.

Example

Run the following command to get a list of all the Compute Engine instances in the my-project project with the word instance followed by a 1 in their full resource name. The results are in descending order by name, and because of the read mask, only the name and location fields are returned.

gcloud asset search-all-resources \
    --scope=projects/my-project \
    --query="name:instance 1" \
    --asset-types=compute.googleapis.com/Instance \
    --order-by="name DESC" \
    --read-mask="name,location"

Example response

---
location: us-central1-a
name: //compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/instance-2-1
---
location: us-central1-a
name: //compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/instance-1

REST

HTTP method and URL:

POST https://cloudasset.googleapis.com/v1/SCOPE_PATH:searchAllResources

Request JSON body:

{
  "query": "QUERY",
  "assetTypes": [
    "ASSET_TYPE_1",
    "ASSET_TYPE_2",
    "..."
  ],
  "orderBy": "ORDER_BY",
  "pageSize": "PAGE_SIZE",
  "pageToken": "PAGE_TOKEN",
  "readMask": "READ_MASK"
}

Provide the following values:

  • SCOPE_PATH: Use one of the following values:

    The allowed values are:

    • projects/PROJECT_ID, where PROJECT_ID is the ID of the project that has the assets you want to search for.

    • projects/PROJECT_NUMBER, where PROJECT_NUMBER is the number of the project that has the assets you want to search for.

      How to find a Google Cloud project number

      Google Cloud console

      To find a Google Cloud project number, complete the following steps:

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

        Go to Welcome

      2. Click the switcher list box in the menu bar.

      3. Select your organization from the list box, and then search for your project name. The project name, project number, and project ID are shown near the Welcome heading.

        Up to 4,000 resources are displayed. If you don't see the project you're looking for, go to the Manage resources page and filter the list using the name of that project.

      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, where FOLDER_ID is the ID of the folder that has the assets you want to search for.

      How to find the ID of a Google Cloud folder

      Google Cloud console

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

      1. Go to the Google Cloud console.

        Go to the Google Cloud console

      2. Click the switcher list box in the menu bar.
      3. Select your organization from the list box.
      4. Search for your folder name. The folder ID is shown next to the folder name.

      gcloud CLI

      You can retrieve the ID of a Google Cloud folder 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 is a partial or full string match for the folder's name. Remove the --format flag to see more information about the found folders.

      The previous command doesn't return the IDs of subfolders within folders. To do so, run the following command using a top level folder's ID:

      gcloud resource-manager folders list --folder=FOLDER_ID

    • organizations/ORGANIZATION_ID, where ORGANIZATION_ID is the ID of the organization that has the assets you want to search for.

      How to find the ID of a Google Cloud organization

      Google Cloud console

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

      1. Go to the Google Cloud console.

        Go to the Google Cloud console

      2. Click the switcher list box in the menu bar.
      3. Select your organization from the list box.
      4. Click the All tab. The organization ID is shown next to the organization name.

      gcloud CLI

      You can retrieve the ID of a Google Cloud organization with the following command:

      gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
  • QUERY: Optional. The query expression. If not specified or empty, all resources are searched for in the specified scope. To learn how to write a search query, see Search query syntax.
  • ASSET_TYPE_#: Optional. An array of searchable asset types. RE2-compatible regular expressions are supported. If the regular expression doesn't match any supported asset type, an INVALID_ARGUMENT error is returned. When assetTypes isn't specified, all asset types are returned.
  • ORDER_BY: Optional. A comma-separated list of fields specifying the sorting order of the results. The default order is ascending. Add DESC after the field name to indicate descending order. See the reference documentation for what fields can be sorted.

  • PAGE_SIZE: Optional. The number of results to return per page. The maximum is 500. If the value is set to 0 or a negative value, an appropriate default is selected. A nextPageToken is returned to retrieve subsequent results.

  • PAGE_TOKEN: Optional. Long request responses are separated over multiple pages. When pageToken isn't specified, the first page is returned. Subsequent pages can be called by using the previous response's