Create and read a report

Learn how to create a App Optimize API report of your Google Cloud spending, monitor the report's generation, and read the resulting data when it is ready for you. In this quickstart guide, you use the REST API.

Before you begin

  1. 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.

  2. 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.
  3. 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.

  4. Install the Google Cloud CLI.

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

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

    gcloud init

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

  8. Install the Google Cloud CLI.

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

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

    gcloud init

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

Required roles

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

  • App Optimize Admin (roles/appoptimize.admin)
  • 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

This example creates a report of the total spending within your chosen PROJECT_ID. The report breaks down the costs by each Google Cloud product used, such as Compute Engine and Cloud Storage, and by the specific SKU and location. The report covers the last three days of data.

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 the report.

  1. Use the following curl command to send the request:

    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",
      "sku"
    ],
    "metrics": [
      "cost"
    ],
    "filter": "hour >= now - duration(\"72h\")"
  }' \
  "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-first-report

    The API returns a Long-Running Operation (LRO) object, which represents the report generation process. Here is an example response:

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

    The "done": false status indicates that the report is still being generated. Note the OPERATION_ID as you will use this in the next step.

  2. Because report generation can take time, you need to poll the LRO to until it indicates that the generation process is complete and the report's data is ready for download.

    To check the status of the generation process, send a HTTP GET request to the operation's resource name:

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

    Examine the response. If "done" is false, wait 5 to 15 seconds and repeat this step. If "done" is true, then the report is ready.

    The following is an example of a response when the operation is complete:

    {
  "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",
    "scopes": [
      {
        "project": "projects/PROJECT_ID"
      }
    ],
    "dimensions": [
      "location",
      "product_display_name",
      "project",
      "sku"
    ],
    "metrics": [
      "cost"
    ],
    "filter": "hour >= now - duration(\"72h\")",
    "expireTime": "2026-02-04T22:05:05Z"
  }
}

Read the report data

To retrieve the report data, use the :read custom method once the LRO is complete:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://appoptimize.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/reports/REPORT_ID:read"

The response contains the report data rows and column definitions. The following is an example of a successful response:

{
  "rows": [
    [
      "us-central1",
      "Compute Engine",
      "projects/PROJECT_ID",
      "6EC2-384A-47D9",
      {
        "currency_code": "USD",
        "units": "25",
        "nanos": 750000000
      }
    ],
    [
      "us-central1",
      "Cloud Storage",
      "projects/PROJECT_ID",
      "9ADA-9ADC-2FBE",
      {
        "currency_code": "USD",
        "units": "5",
        "nanos": 100000000
      }
    ],
    [
      "europe-west1",
      "Compute Engine",
      "projects/PROJECT_ID",
      "6EC2-384A-47D9",
      {
        "currency_code": "USD",
        "units": "18",
        "nanos": 500000000
      }
    ],
    [
      "us-central1",
      "Compute Engine",
      "projects/PROJECT_ID",
      "F61D-4D51-AAFC",
      {
        "currency_code": "USD",
        "units": "12",
        "nanos": 200000000
      }
    ]
  ],
  "columns": [
    {
      "name": "location",
      "type": "STRING",
      "mode": "NULLABLE"
    },
    {
      "name": "product_display_name",
      "type": "STRING",
      "mode": "NULLABLE"
    },
    {
      "name": "project",
      "type": "STRING",
      "mode": "NULLABLE"
    },
    {
      "name": "sku",
      "type": "STRING",
      "mode": "NULLABLE"
    },
    {
      "name": "cost",
      "type": "RECORD",
      "mode": "NULLABLE",
      "columns": [
        {
          "name": "currency_code",
          "type": "STRING",
          "mode": "NULLABLE"
        },
        {
          "name": "units",
          "type": "INT64",
          "mode": "NULLABLE"
        },
        {
          "name": "nanos",
          "type": "INT64",
          "mode": "NULLABLE"
        }
      ]
    }
  ],
  "next_page_token": ""
}

Reports with many rows are paginated. To handle multiple pages, see Read a report's data.

To understand the values in the cost field, see Interpreting cost metrics. For more information on the data and to understand its limitations, see Understanding the data.

Clean up

App Optimize API automatically deletes your report 24 hours after it is created. To delete the report sooner, send a HTTP DELETE request to the report's resource endpoint:

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

What's next