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.

This project is chosen by you and is identified by PROJECT_ID. For simplicity, in this guide your project will both host the report resource and provide the data scope.

App Optimize API supports creating reports in one project that analyzes data from a different source project or from applications in single-project or folder-level boundaries. If you are generating 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. In the examples in this documentation, this is the project identified by PROJECT_ID.

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.

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.

To initialize the gcloud CLI, run the following command:

gcloud init

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

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.

To initialize the gcloud CLI, run the following command:

gcloud init

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

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, send a HTTP POST request to the REST API's projects.locations.reports resource path.

Follow these steps to create a report.

Use the following curl command to send the request. The request body contains the report definition, including the requested scope, dimensions, metrics, and any filters.

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

Required roles

Create a report

Concurrency limits

What's next

Create a report