- [HTTP request](https://docs.cloud.google.com/compute/docs/reference/rest/beta/advice/calendarMode#body.HTTP_TEMPLATE)
- [Path parameters](https://docs.cloud.google.com/compute/docs/reference/rest/beta/advice/calendarMode#body.PATH_PARAMETERS)
- [Request body](https://docs.cloud.google.com/compute/docs/reference/rest/beta/advice/calendarMode#body.request_body)
  - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/beta/advice/calendarMode#body.request_body.SCHEMA_REPRESENTATION)
    - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/beta/advice/calendarMode#body.request_body.SCHEMA_REPRESENTATION.future_resources_specs.map_entry1.value.SCHEMA_REPRESENTATION)
    - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/beta/advice/calendarMode#body.request_body.SCHEMA_REPRESENTATION.future_resources_specs.map_entry1.value.SCHEMA_REPRESENTATION_1)
    - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/beta/advice/calendarMode#body.request_body.SCHEMA_REPRESENTATION.future_resources_specs.map_entry1.value.SCHEMA_REPRESENTATION_2)
      - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/beta/advice/calendarMode#body.request_body.SCHEMA_REPRESENTATION.future_resources_specs.map_entry1.value.SCHEMA_REPRESENTATION_2.specific_sku_resources.SCHEMA_REPRESENTATION)
- [Response body](https://docs.cloud.google.com/compute/docs/reference/rest/beta/advice/calendarMode#body.response_body)
  - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/beta/advice/calendarMode#body.CalendarModeAdviceResponse.SCHEMA_REPRESENTATION)
- [Authorization scopes](https://docs.cloud.google.com/compute/docs/reference/rest/beta/advice/calendarMode#body.aspect)
- [IAM Permissions](https://docs.cloud.google.com/compute/docs/reference/rest/beta/advice/calendarMode#body.aspect_1)
- [Try it!](https://docs.cloud.google.com/compute/docs/reference/rest/beta/advice/calendarMode#try-it)

Advise how, where and when to create the requested amount of instances with specified accelerators, within the specified time and location limits. The method recommends creating future reservations for the requested resources.

### HTTP request

Choose an endpoint:
global africa-south1 asia-east1 asia-east2 asia-northeast1 asia-northeast2 asia-northeast3 asia-south1 asia-south2 asia-southeast1 asia-southeast2 asia-southeast3 australia-southeast1 australia-southeast2 europe-central2 europe-north1 europe-north2 europe-southwest1 europe-west1 europe-west10 europe-west12 europe-west2 europe-west3 europe-west4 europe-west6 europe-west8 europe-west9 me-central1 me-central2 me-west1 northamerica-northeast1 northamerica-northeast2 northamerica-south1 southamerica-east1 southamerica-west1 us-central1 us-east1 us-east4 us-east5 us-south1 us-west1 us-west2 us-west3 us-west4   
`POST https://compute.googleapis.com/compute/beta/projects/{project}/regions/{region}/advice/calendarMode`

<br />

The URLs use [gRPC Transcoding](https://google.aip.dev/127) syntax.

### Path parameters

| Parameters ||
|---|---|
| `project` | `string` Project ID for this request. |
| `region` | `string` Name of the region for this request. |

### Request body

The request body contains data with the following structure:

| JSON representation |
|---|
| ``` { "futureResourcesSpecs": { string: { "locationPolicy": { "locations": { string: { "preference": enum }, ... } }, "timeRangeSpec": { "startTimeNotEarlierThan": string, "startTimeNotLaterThan": string, "endTimeNotEarlierThan": string, "endTimeNotLaterThan": string, "minDuration": string, "maxDuration": string }, "targetResources": { // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "specificSkuResources": { "machineType": string, "localSsdPartitions": [ { "diskInterface": enum, "diskSizeGb": string } ], "instanceCount": string }, "aggregateResources": { "vmFamily": enum, "workloadType": enum, "acceleratorCount": string } // End of mutually exclusive fields. }, "deploymentType": enum }, ... } } ``` |

| Fields ||
|---|---|
| `futureResourcesSpecs[]` | `map (key: string, value: object)` Specification of resources to create in the future. The key of the map is an arbitrary string specified by the caller. Value of the map is a specification of required resources and their constraints. Currently only one value is allowed in this map. |
| `futureResourcesSpecs[].locationPolicy` | `object` Optional location policy allowing to exclude some zone(s) in which the resources must not be created. |
| `futureResourcesSpecs[].locationPolicy.locations[]` | `map (key: string, value: object)` Preferences for specified locations. Keys of the map are locations - zones, in format of 'zones/'. Values are preferences for the zones. If a zone is not specified in this map, it is ALLOWed. |
| `futureResourcesSpecs[].locationPolicy.locations[].preference` | `enum` Preference for this location. |
| `futureResourcesSpecs[].timeRangeSpec` | `object` Specification of a time range in which the resources may be created. The time range specifies start of resource use and planned end of resource use. |
| `futureResourcesSpecs[].timeRangeSpec.startTimeNotEarlierThan` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `futureResourcesSpecs[].timeRangeSpec.startTimeNotLaterThan` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `futureResourcesSpecs[].timeRangeSpec.endTimeNotEarlierThan` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `futureResourcesSpecs[].timeRangeSpec.endTimeNotLaterThan` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `futureResourcesSpecs[].timeRangeSpec.minDuration` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#duration` format)`` A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `"3.5s"`. |
| `futureResourcesSpecs[].timeRangeSpec.maxDuration` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#duration` format)`` A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `"3.5s"`. |
| `futureResourcesSpecs[].targetResources` | `object` Specification of the reserved resources. |
| `futureResourcesSpecs[].targetResources.specificSkuResources` | `object` |
| `futureResourcesSpecs[].targetResources.specificSkuResources.machineType` | `string` The machine type to use for instances that will use the reservation. This field only accepts machine type names. e.g. n2-standard-4 and does not accept machine type full or partial url. e.g. projects/my-l7ilb-project/zones/us-central1-a/machineTypes/n2-standard-4. Use for GPU reservations. |
| `futureResourcesSpecs[].targetResources.specificSkuResources.localSsdPartitions[]` | `object` Local SSD partitions. You do not have to include SSD partitions that are built in the machine type. |
| `futureResourcesSpecs[].targetResources.specificSkuResources.localSsdPartitions[].diskInterface` | `enum` Disk interface. Defaults to SCSI. |
| `futureResourcesSpecs[].targetResources.specificSkuResources.localSsdPartitions[].diskSizeGb` | `string (https://developers.google.com/discovery/v1/type-format format)` The size of the disk in GB. |
| `futureResourcesSpecs[].targetResources.specificSkuResources.instanceCount` | `string (https://developers.google.com/discovery/v1/type-format format)` Size of the request, in instance count. |
| `futureResourcesSpecs[].targetResources.aggregateResources` | `object` |
| `futureResourcesSpecs[].targetResources.aggregateResources.vmFamily` | `enum` The VM family that all instances scheduled against this reservation must belong to. Use for TPU reservations. |
| `futureResourcesSpecs[].targetResources.aggregateResources.workloadType` | `enum` Workload type. Use for TPU reservations. |
| `futureResourcesSpecs[].targetResources.aggregateResources.acceleratorCount` | `string (https://developers.google.com/discovery/v1/type-format format)` Size of the request, in accelerator (chip) count. |
| `futureResourcesSpecs[].deploymentType` | `enum` Indicates if the reservation allocation strategy is static (DENSE) or dynamic (STANDARD). Defaults to DENSE. |

### Response body

A response containing the recommended way of creating the specified resources in the future. It contains (will contain) multiple recommendations that can be analyzed by the customer and the best one can be picked.

If successful, the response body contains data with the following structure:

| JSON representation |
|---|
| ``` { "recommendations": [ { "recommendationsPerSpec": { string: { "recommendationId": string, "recommendationType": enum, "startTime": string, "endTime": string, "location": string, "otherLocations": { string: { "status": enum, "details": string }, ... } }, ... } } ] } ``` |

| Fields ||
|---|---|
| `recommendations[]` | `object` Recommendations where, how and when to create the requested resources in order to maximize their obtainability and minimize cost. |
| `recommendations[].recommendationsPerSpec[]` | `map (key: string, value: object)` Recommendations for every future resource specification passed in CalendarModeAdviceRequest. Keys of the map correspond to keys specified in the request. |
| `recommendations[].recommendationsPerSpec[].recommendationId` | `string` Unique id of the recommendation, a UUID string generated by the API. |
| `recommendations[].recommendationsPerSpec[].recommendationType` | `enum` Type of recommendation. Currently only FUTURE_RESERVATION is supported. |
| `recommendations[].recommendationsPerSpec[].startTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `recommendations[].recommendationsPerSpec[].endTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `recommendations[].recommendationsPerSpec[].location` | `string` The advised location for resource usage. When a zone, in format 'zones/'. If not set, it means that no location is recommended - see otherLocations for details. |
| `recommendations[].recommendationsPerSpec[].otherLocations[]` | `map (key: string, value: object)` List of locations in the request scope that were not recommended. Keys of the map are zones, in format 'zones/'. The values are status information indicating the recommendation status. |
| `recommendations[].recommendationsPerSpec[].otherLocations[].status` | `enum` Status of recommendation in this location. |
| `recommendations[].recommendationsPerSpec[].otherLocations[].details` | `string` Details (human readable) describing the situation. For example, if status is CONDITION_NOT_MET, then details contain information about the parameters of the time window that did not meet the required conditions. |

### Authorization scopes

Requires one of the following OAuth scopes:

- `https://www.googleapis.com/auth/compute`
- `
  https://www.googleapis.com/auth/cloud-platform`

For more information, see the [Authentication Overview](https://docs.cloud.google.com/docs/authentication#authorization-gcp).

### IAM Permissions

In addition to any permissions specified on the fields above, authorization requires one or more of the following [IAM](https://cloud.google.com/iam/docs/) permissions:

- `compute.advice.calendarMode`

To find predefined roles that contain those permissions, see [Compute Engine IAM Roles](https://docs.cloud.google.com/compute/docs/access/iam).