Create a report

App Optimize API helps you analyze your cost and resource utilization data by generating reports. To get this information, you first create a report by sending an API request. In this request, you define the scope of the data, how it should be aggregated or grouped, and any filters to apply.

When the report is ready, you can then read the data.

For information on available scopes, dimensions, metrics, and filters, and valid combinations of these settings, see About reports.

Before you begin

The examples in this guide require a Google Cloud project with active resources to analyze. App Optimize API needs billing and utilization data to produce meaningful results; reports run against new or empty projects will be empty.

In this guide, the project identified as PROJECT_ID provides the data scope and hosts the report resource.

App Optimize API does support creating reports in one project that analyzes data from another project or from applications in single-project or folder-level boundaries. To generate a report on an App Hub application, which can be made up of multiple projects, you must have the required monitoring and billing permissions on all of the application's associated projects to create the report.
Ensure that the App Optimize API is enabled for the project you will use to create and manage the report resource.

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.
Verify that you have the permissions required to complete this guide.

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

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

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.
1. Install the Google Cloud CLI.
2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
3. If you're using a local shell, then create local authentication credentials for your user account:
```
gcloud auth application-default login
```
  You don't need to do this if you're using Cloud Shell.
  
  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.

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

For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Required roles

To get the permissions that you need to create a report using this guide, ask your administrator to grant you the following IAM roles on your project with active resources:

App Optimize Admin (roles/appoptimize.admin)
Monitoring Viewer (roles/monitoring.viewer)
Viewer (roles/viewer) (or another role granting billing.resourceCosts.get)

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.

For more information about permissions and roles required for App Optimize API, see Access control with IAM.

Create a report

The following steps describe how to initiate report creation. This example creates a report to help you understand your chosen project's costs and average CPU usage over the last week. The report breaks down this information by each individual resource, including what type of resource it is, the Google Cloud product it's part of, and its location.

To create the report resource, follow the instructions for your preferred method:

gcloud

Use the following gcloud beta app-optimize reports create command to create your report.

gcloud beta app-optimize reports create REPORT_ID \
  --project=PROJECT_ID \
  --location=global \
  --dimensions=location,product_display_name,project,resource,resource_type \
  --metrics=cost,cpu_mean_utilization \
  --report-filter='hour >= now - duration("168h")' \
  --scopes=project=projects/PROJECT_ID

Replace the following:

REPORT_ID: a unique ID for your new report—for example, my-resource-cost-report-1.
PROJECT_ID: your Google Cloud project ID.

The command to create a report automatically waits for the operation to complete.

Python

The following Python code uses AppOptimizeClient.create_report() to create a report.

from google.cloud import appoptimize_v1beta

project_id = "PROJECT_ID"
report_id = "REPORT_ID"

# Create the App Optimize client
client = appoptimize_v1beta.AppOptimizeClient()

# Initialize the report request
report = appoptimize_v1beta.Report(
    dimensions=['location', 'product_display_name', 'project', 'resource', 'resource_type'],
    metrics=['cost', 'cpu_mean_utilization'],
    filter='hour >= now - duration("168h")',
    scopes=[
        appoptimize_v1beta.Scope(project=f"projects/{project_id}"),
    ],
)
request = appoptimize_v1beta.CreateReportRequest(
    parent=f"projects/{project_id}/locations/global",
    report=report,
    report_id=report_id,
)

# Send the request and wait for completion
operation = client.create_report(request=request)
print("Waiting for operation to complete...")
response = operation.result()
print(response)

Replace the following:

PROJECT_ID: your Google Cloud project ID.
REPORT_ID: a unique ID for your new report—for example, my-first-report.

The operation.result() method in the client library automatically waits for the operation to complete. No manual polling loop is required.

REST

Send an HTTP POST request to the REST API's projects.locations.reports resource path

To send the request, use the following curl command:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": [
      {
        "project": "projects/PROJECT_ID"
      }
    ],
    "dimensions": [
      "location",
      "product_display_name",
      "project",
      "resource",
      "resource_type"
    ],
    "metrics": [
      "cost",
      "cpu_mean_utilization"
    ],
    "filter": "hour >= now - duration(\"168h\")"
  }' \
  "https://appoptimize.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/reports?report_id=REPORT_ID"

Replace the following:

PROJECT_ID: your Google Cloud project ID.
REPORT_ID: a unique ID for your new report—for example, my-resource-cost-report-1.

The API returns a long-running operation (LRO) object. Note the name field in the response, which you'll use to check the operation's status:

{
  "name": "projects/PROJECT_ID/locations/global/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.appoptimize.v1beta.OperationMetadata"
  },
  "done": false
}

In the response, the done field is false, indicating that the report generation is in progress.

To check if the report is ready, send a GET HTTP request to the operation name returned in the previous step:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://appoptimize.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/operations/OPERATION_ID"

Replace PROJECT_ID and OPERATION_ID with the values from the LRO response.

Examine the response to determine the operation's status:

If the report is still being generated, the response will look similar to the initial LRO response, with done set to false. You should wait a short period, such as 5 to 15 seconds, and poll again by repeating this step.

When the report generation is complete, the response will have "done": true and include the report resource in the response field:

  {
    "name": "projects/PROJECT_ID/locations/global/operations/OPERATION_ID",
    "metadata": {
      "@type": "type.googleapis.com/google.cloud.appoptimize.v1beta.OperationMetadata"
    },
    "done": true,
    "response": {
      "@type": "type.googleapis.com/google.cloud.appoptimize.v1beta.Report",
      "name": "projects/PROJECT_ID/locations/global/reports/REPORT_ID",
      "dimensions": [
        "location",
        "product_display_name",
        "project",
        "resource",
        "resource_type"
      ],
      "scopes": [
        {
          "project": "projects/PROJECT_ID"
        }
      ],
      "filter": "hour >= now - duration(\"168h\")",
      "expireTime": "2026-02-05T18:50:25.273833857Z",
      "metrics": [
        "cost",
        "cpu_mean_utilization"
      ]
    }
  }
  ```

If the LRO encounters an error, the response will contain an error field instead of the response field, providing details about the failure.

Once the operation is successfully complete, you can read the report's data.

Concurrency limits

When you create a report, App Optimize API gets cost data from Cloud Billing and utilization data from Cloud Monitoring for each target_project of the report.

For a report scoped to a single project, that project is the target project.
For an App Hub application, each project that contains a service or workload in the application is a target project.

App Optimize API enforces a concurrency quota called Concurrent CreateReport operations, which allows a maximum of 10 concurrent requests for report data per target project. When you create a report, App Optimize API calculates the number of target projects in the report and locks the required number of quota units until the LRO for creating the report is finished.

Reports that complete in less than a few minutes might not be counted against your concurrency limit due to system-level measurement timing.

You can view your current API activity and manage these limits on the Quotas & System Limits page in the Google Cloud console.

If you plan to create multiple reports concurrently, consider when your teams run reports and how your App Hub applications are structured:

If multiple teams run reports that include the same target projects, you can stagger the start times for report creation for each team.
Applications can include resources from multiple projects, and more than one application might use resources from a single project. Creating reports concurrently for these types of applications results in multiple requests to target projects.

For example, consider a team that works on a suite of applications for learning creative arts, with standard and premium variants. The following table shows the list of applications in the first column. In the remaining columns, the check mark icon () indicates that a project contains services or workloads for a listed application.

Application	common-project	dance-project	draw-project	animate-project	music-project
dance-app
draw-app
music-app
animate-app
choreograph-app
storyteller-app
dance-premium-app
draw-premium-app
music-premium-app
animate-premium-app
choreograph-premium-app
storyteller-premium-app

If you create reports for cost and utilization data for all listed applications at the same time, App Optimize API uses more than one unit of your concurrency limit in some projects. In particular, the shared project common-project receives 12 requests for cost and utilization data. Since this number exceeds the concurrency limit, 2 of data requests will fail.

To prevent this issue, the team could run reports for the standard versions of the applications first and then run reports for the premium version.

What's next

To understand dimensions, metrics, and filters, see About reports.
Explore other ways to manage reports:

Create a report Stay organized with collections Save and categorize content based on your preferences.

Before you begin

gcloud

Python

REST

Required roles

Create a report

gcloud

Python

REST

Concurrency limits

What's next

Create a report