- [HTTP request](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacity#body.HTTP_TEMPLATE)
- [Path parameters](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacity#body.PATH_PARAMETERS)
- [Request body](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacity#body.request_body)
  - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacity#body.request_body.SCHEMA_REPRESENTATION)
    - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacity#body.request_body.SCHEMA_REPRESENTATION.instance_properties.SCHEMA_REPRESENTATION)
    - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacity#body.request_body.SCHEMA_REPRESENTATION.instance_flexibility_policy.inlinedField.map_entry1.value.SCHEMA_REPRESENTATION)
    - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacity#body.request_body.SCHEMA_REPRESENTATION.instance_flexibility_policy.inlinedField.map_entry1.value.SCHEMA_REPRESENTATION_1)
    - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacity#body.request_body.SCHEMA_REPRESENTATION.distribution_policy.SCHEMA_REPRESENTATION)
- [Response body](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacity#body.response_body)
  - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacity#body.CapacityAdviceResponse.SCHEMA_REPRESENTATION)
    - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacity#body.CapacityAdviceResponse.SCHEMA_REPRESENTATION.recommendations.SCHEMA_REPRESENTATION)
    - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacity#body.CapacityAdviceResponse.SCHEMA_REPRESENTATION.recommendations.SCHEMA_REPRESENTATION_1)
- [Authorization scopes](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacity#body.aspect)
- [IAM Permissions](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacity#body.aspect_1)
- [Try it!](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacity#try-it)

Advice on making real-time decisions (such as choosing zone or machine types) during deployment to maximize your chances of obtaining capacity.

### 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/v1/projects/{project}/regions/{region}/advice/capacity`

<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 |
|---|
| ``` { "instanceProperties": { "scheduling": { "provisioningModel": enum } }, "instanceFlexibilityPolicy": { "instanceSelections": { string: { "machineTypes": [ string ], "guestAccelerators": [ { "acceleratorType": string, "acceleratorCount": integer } ], "disks": [ { "type": enum } ] }, ... } }, "size": integer, "distributionPolicy": { "zones": [ { "zone": string } ], "targetShape": enum } } ``` |

| Fields ||
|---|---|
| `instanceProperties` | `object` Instance properties for this request. |
| `instanceProperties.scheduling` | `object` Specifies the scheduling options. |
| `instanceProperties.scheduling.provisioningModel` | `enum` Specifies the provisioning model. |
| `instanceFlexibilityPolicy.instanceSelections[].key` | `string` |
| `instanceFlexibilityPolicy.instanceSelections[].value.machineTypes[]` | `string` Full machine-type names, e.g. "n1-standard-16". |
| `instanceFlexibilityPolicy.instanceSelections[].value.guestAccelerators[].acceleratorType` | `string` Full or partial URL of the accelerator type resource to attach to this instance. For example: `projects/my-project/zones/us-central1-c/acceleratorTypes/nvidia-tesla-p100` If you are creating an instance template, specify only the accelerator name. See [GPUs on Compute Engine](https://docs.cloud.google.com/compute/docs/gpus#introduction) for a full list of accelerator types. |
| `instanceFlexibilityPolicy.instanceSelections[].value.guestAccelerators[].acceleratorCount` | `integer` The number of the guest accelerator cards exposed to this instance. |
| `instanceFlexibilityPolicy.instanceSelections[].value.disks[]` | `object` Local SSDs. |
| `instanceFlexibilityPolicy.instanceSelections[].value.disks[].type` | `enum` Specifies the type of the disk. |
| `size` | `integer` The number of VM instances to request. |
| `distributionPolicy` | `object` Policy specifying the distribution of instances across zones within the requested region. |
| `distributionPolicy.zones[]` | `object` Zones where advice.capacity Advisor looks for capacity. |
| `distributionPolicy.zones[].zone` | `string` The URL of the [zone](https://docs.cloud.google.com/compute/docs/regions-zones#available). It can be a partial or full URL. For example, the following are valid values: - `https://www.googleapis.com/compute/v1/projects/project/zones/zone` - `projects/project/zones/zone` - `zones/zone` <br /> |
| `distributionPolicy.targetShape` | `enum` Target distribution shape. You can specify the following values: `ANY`, `ANY_SINGLE_ZONE`, or `BALANCED`. |

### Response body

A response contains scoring recommendations.

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

| JSON representation |
|---|
| ``` { "recommendations": [ { "scores": { "obtainability": number, "estimatedUptime": string }, "shards": [ { "zone": string, "machineType": string, "instanceCount": integer, "provisioningModel": enum } ] } ] } ``` |

| Fields ||
|---|---|
| `recommendations[]` | `object` Initially the API will provide one recommendation which balances the individual scores according to the service provider's preference. |
| `recommendations[].scores` | `object` Scores for the recommendation. |
| `recommendations[].scores.obtainability` | `number` The obtainability score indicates the likelihood of successfully obtaining (provisioning) the requested number of VMs. The score range is 0.0 through 1.0. Higher is better. |
| `recommendations[].scores.estimatedUptime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#duration` format)`` The estimated run time of the majority of Spot VMs in the request before preemption. The estimate is best-effort only. It is based on historical data and current conditions. A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `"3.5s"`. |
| `recommendations[].shards[]` | `object` Shards represent blocks of uniform capacity in recommendations. |
| `recommendations[].shards[].zone` | `string` Output only. The zone name for this shard. |
| `recommendations[].shards[].machineType` | `string` The machine type corresponds to the instance selection in the request. |
| `recommendations[].shards[].instanceCount` | `integer` The number of instances. |
| `recommendations[].shards[].provisioningModel` | `enum` The provisioning model that you want to view recommendations for. |

### 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.capacity`

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