# Method: projects.locations.usageHistories.query

- [HTTP request](https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/projects.locations.usageHistories/query#body.HTTP_TEMPLATE)
- [Path parameters](https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/projects.locations.usageHistories/query#body.PATH_PARAMETERS)
- [Request body](https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/projects.locations.usageHistories/query#body.request_body)
  - [JSON representation](https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/projects.locations.usageHistories/query#body.request_body.SCHEMA_REPRESENTATION)
- [Response body](https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/projects.locations.usageHistories/query#body.response_body)
- [Authorization scopes](https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/projects.locations.usageHistories/query#body.aspect)
- [IAM Permissions](https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/projects.locations.usageHistories/query#body.aspect_1)

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=projects/*/locations/*}/usageHistories:query`

The URL uses [gRPC Transcoding](https://google.aip.dev/127) 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 (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/LocationType`), "isSpot": boolean, "machineFamily": string, "machineShape": { object (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/MachineShape`) }, "diskType": string, "confidentialMode": boolean, "gpuType": string, "tpuType": string, "gcsBucketTraffic": { object (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/GcsBucketTraffic`) }, "cloudResourceType": string, "usageAggregationMethod": enum (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/AggregationMethod`), "startDate": { object (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/Date`) }, "endDate": { object (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/Date`) } } ``` |

| Fields ||
|---|---|
| `locationLevel` | ``enum (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/LocationType`)`` Optional. The location level of the reservations usage timeseries. |
| `isSpot` | `boolean` Optional. The isSpot flag is used to fetch the usage data for preemptible Resources. |
| `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 (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/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. |
| `confidentialMode` | `boolean` Optional. Whether the persistent disk is in confidential mode. |
| `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. |
| `gcsBucketTraffic` | ``object (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/GcsBucketTraffic`)`` Optional. Cloud Storage bucket traffic resource for the `UsageHistory` values to return. |
| `cloudResourceType` | `string` Required. 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" and "gcs-bucket-read-throughput". |
| `usageAggregationMethod` | ``enum (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/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 (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/Date`)`` Optional. The start date of reservations usage. |
| `endDate` | ``object (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/Date`)`` Optional. The end date of reservations usage. |

### Response body

If successful, the response body contains an instance of `https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/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](https://docs.cloud.google.com/docs/authentication#authorization-gcp).

### IAM Permissions

Requires the following [IAM](https://cloud.google.com/iam/docs) permission on the `parent` resource:

- `capacityplanner.usageHistories.list`

For more information, see the [IAM documentation](https://cloud.google.com/iam/docs).