Method: folders.locations.usageHistories.query

Returns a list of the usage histories that are in the parent parameter and match your specified filters.

HTTP request

POST https://capacityplanner.googleapis.com/v1beta/{parent=folders/*/locations/*}/usageHistories:query

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
parent

string

Required. The compute engine resource and location for the time series values to return. The format is:

projects/{project}/locations/{location} or
organizations/{organization}/locations/{location} or
folders/{folder}/locations/{location}

Request body

The request body contains data with the following structure:

JSON representation 
{
  "locationLevel": enum (LocationType),
  "machineFamily": string,
  "machineShape": {
    object (MachineShape)
  },
  "diskType": string,
  "gpuType": string,
  "tpuType": string,
  "cloudResourceType": string,
  "usageAggregationMethod": enum (AggregationMethod),
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  }
}
Fields
locationLevel

enum (LocationType)

Optional. The location level of the reservations usage timeseries.
machineFamily

string

The machine family for the UsageHistory values to return. Possible values include "n1", and "n2d". See https://cloud.google.com/compute/docs/machine-types for more examples. Empty machineFamily will return results matching all machine families.
machineShape

object (MachineShape)

Optional. The machine shape for the UsageHistory values to return.
diskType

string

Optional. The diskType for the UsageHistory values to return request with persistent-disk cloudResourceType. Empty diskType will return results matching all disk types.
gpuType

string

Optional. The GPU type for the UsageHistory values to return. Sample values are "nvidia-tesla-t4", and "nvidia-tesla-a100". See https://cloud.google.com/compute/docs/gpus for a list. Empty gpuType will return results matching all GPUs.
tpuType

string

Optional. The TPU type for the UsageHistory values to return. Empty tpuType will return results matching all TPUs.
cloudResourceType

string

The resource for the UsageHistory values to return. Possible values include "gce-vcpus", "gce-ram", "gce-local-ssd", "gce-persistent-disk", "gce-gpu" and "gce-tpu". Empty cloudResourceType will return results matching all resources.
usageAggregationMethod

enum (AggregationMethod)

The method that should be used to convert sampled usage data to daily usage values. AGGREGATION_METHOD_UNSPECIFIED will return results matching all the aggregation methods.
startDate

object (Date)

Optional. The start date of reservations usage.
endDate

object (Date)

Optional. The end date of reservations usage.

Response body

If successful, the response body contains an instance of QueryUsageHistoriesResponse.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/devstorage.full_control

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the parent resource:

  • capacityplanner.usageHistories.list

For more information, see the IAM documentation.