# Method: organizations.locations.forecasts.query

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

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

### HTTP request

`POST https://capacityplanner.googleapis.com/v1beta/{parent=organizations/*/locations/*}/forecasts: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 |
|---|
| ``` { "machineFamily": string, "machineShape": { object (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/MachineShape`) }, "diskType": string, "confidentialMode": boolean, "gpuType": string, "tpuType": string, "cloudResourceType": string, "forecastType": enum (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/ForecastType`), "predictionInterval": enum (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/PredictionInterval`), "aggregationMethod": 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`) }, "generationDate": { object (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/Date`) } } ``` |

| Fields ||
|---|---|
| `machineFamily` | `string` The machine family to use to select the `Forecast` values to return. Possible values include "n1", and "n2d". 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 time series values to return. |
| `diskType` | `string` Optional. The diskType for the `Forecast` values to return with request 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 `Forecast` 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 `Forecast` values to return. Empty tpuType will return results matching all TPUs. |
| `cloudResourceType` | `string` Required. The resource for the `Forecast` values to return. Possible values include "gce-vcpus", "gce-ram", "gce-local-ssd", "gce-persistent-disk", "gce-gpu" and "gce-tpu". |
| `forecastType` | ``enum (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/ForecastType`)`` The type of forecast to use to select the `Forecast` values to return. FORECAST_TYPE_UNSPECIFIED will return results matching all the forecast types. |
| `predictionInterval` | ``enum (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/PredictionInterval`)`` The prediction interval to use to select the `Forecast` values to return. PREDICTION_INTERVAL_UNSPECIFIED will return results matching all prediction intervals. |
| `aggregationMethod` | ``enum (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/AggregationMethod`)`` Aggregation Method of the historical usage for which the forecast is generated |
| `startDate` | ``object (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/Date`)`` Optional. The start date (inclusive) from which you want the `Forecast` records to be returned. |
| `endDate` | ``object (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/Date`)`` Optional. The last date (inclusive) until which you want the `Forecast` records to be returned. |
| `generationDate` | ``object (`https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/Date`)`` Optional. If you specify a date for this field, then the API returns the `Forecast` snapshot data that was calculated on the provided `generationDate`. If you don't specify a date for this field, then the API returns the most recently generated forecast. |

### Response body

If successful, the response body contains an instance of `https://docs.cloud.google.com/capacity-planner/docs/reference/rest/v1beta/QueryForecastsResponse`.

### 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.forecasts.list`

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