List reports

Manage your App Optimize API reports effectively by listing all report configurations within your Google Cloud project. This helps you identify a specific report to read its data or delete it ahead of its expiry date if it's no longer needed.

The list operation returns the report metadata, including the resource name, scope, dimensions, metrics, and expiration time for each report. To download the requested cost and usage information, you need to read the report's data.

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. Install the Google Cloud CLI.

  3. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  4. To initialize the gcloud CLI, run the following command: 

    gcloud init

  5. Verify that you have the permissions required to complete this guide.

  6. Install the Google Cloud CLI.

  7. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  8. To initialize the gcloud CLI, run the following command: 

    gcloud init

  9. Verify that you have the permissions required to complete this guide.

Required roles

To get the permissions that you need to list a project's report resources, ask your administrator to grant you the App Optimize Viewer (roles/appoptimize.viewer) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

List reports

To list reports in a project, using the REST API, send a HTTP GET request to the reports collection endpoint.

Use the following curl command to list the reports for a project:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://appoptimize.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/reports?pageSize=PAGE_SIZE"

Replace the following:

  • PROJECT_ID: the ID of the Google Cloud project that owns the report resources that you want to list.
  • PAGE_SIZE: the maximum number of reports to return per page. If omitted, the API uses a default value. The server might return fewer reports than requested.

If the request is successful, the API returns a JSON response containing a list of report resources. Here is an example successful call response:

{
  "reports": [
    {
      "name": "projects/PROJECT_ID/locations/global/reports/my-first-report",
      "dimensions": [
        "location",
        "product_display_name",
        "project",
        "sku"
      ],
      "scopes": [
        {
          "project": "projects/PROJECT_ID"
        }
      ],
      "filter": "hour \u003e= now - duration(\"168h\")",
      "expireTime": "2026-02-05T18:30:39.907639266Z",
      "metrics": [
        "cost"
      ]
    },
    {
      "name": "projects/PROJECT_ID/locations/global/reports/my-second-report",
      "dimensions": [
        "location",
        "product_display_name",
        "project",
        "resource",
        "resource_type"
      ],
      "scopes": [
        {
          "project": "projects/PROJECT_ID"
        }
      ],
      "filter": "hour \u003e= now - duration(\"168h\")",
      "expireTime": "2026-02-05T18:50:25.273833857Z",
      "metrics": [
        "cost",
        "cpu_mean_utilization"
      ]
    }
  ]
}

The reports array contains the metadata for each report. If the request is unsuccessful, review the error message returned by the API.

If the response includes a nextPageToken string, it means there are more reports to retrieve.

Check the response for a nextPageToken field. If the token exists, run the following curl request to retrieve the next page, including the pageToken query parameter. You can continue to use the pageSize parameter.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://appoptimize.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/reports?pageToken=NEXT_PAGE_TOKEN&pageSize=PAGE_SIZE"

Replace the following:

  • NEXT_PAGE_TOKEN: the value of the nextPageToken received in the previous response.
  • PAGE_SIZE: the page size you want for this request.

Repeat this process until the response no longer contains a nextPageToken, which indicates that you have retrieved all reports.

What's next