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
-
Verify that you have the permissions required to complete this guide.
Select the tab for how you plan to use the samples in this document:
gcloud
Install the Google Cloud CLI.
Configure the gcloud CLI to use your federated identity.
For more information, see Sign in to the gcloud CLI with your federated identity.
To initialize the gcloud CLI, run the following command:
gcloud initAfter initializing the gcloud CLI, update it and install the required components:
gcloud components update gcloud components install beta
For information about setting up authentication for a production environment, see Set up Application Default Credentials for code running on Google Cloud in the Google Cloud authentication documentation.
Python
- Install the Python client library for App Optimize API.
-
To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
-
Install the Google Cloud CLI.
-
-
Configure the gcloud CLI to use your federated identity.
For more information, see Sign in to the gcloud CLI with your federated identity.
-
Create local authentication credentials for your user account:
gcloud auth application-default login
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.
For information about setting up authentication for a production environment, see Set up Application Default Credentials for code running on Google Cloud in the Google Cloud authentication documentation.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI, and then sign in to the gcloud CLI with your federated identity.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
For information about setting up authentication for a production environment, see Set up Application Default Credentials for code running on Google Cloud in the Google Cloud authentication documentation.
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, follow the instructions for your preferred method:
gcloud
Use the gcloud beta app-optimize reports list command to list the reports
in a project.
gcloud beta app-optimize reports list \
--project=PROJECT_ID \
--location=global
Replace PROJECT_ID with the ID of the Google Cloud
project that owns the report resources that you want to list.
The gcloud command handles pagination automatically, returning all
requested resources.
Python
The following Python code uses AppOptimizeClient.list_reports() to display a
list of reports in a project.
from google.cloud import appoptimize_v1beta
project_id = "PROJECT_ID"
# Create the App Optimize client and request the project's reports
client = appoptimize_v1beta.AppOptimizeClient()
request = appoptimize_v1beta.ListReportsRequest(
parent=f"projects/{project_id}/locations/global"
)
page_result = client.list_reports(request=request)
# Iterate over the list of reports and display each one
for response in page_result:
print(response)
Replace PROJECT_ID with the ID of the Google Cloud
project that owns the report resources that you want to list.
The client library handles pagination automatically, yielding results from the iterator.
REST
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 command 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 thenextPageTokenreceived 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.