- [HTTP request](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacityHistory#body.HTTP_TEMPLATE)
- [Path parameters](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacityHistory#body.PATH_PARAMETERS)
- [Request body](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacityHistory#body.request_body)
  - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacityHistory#body.request_body.SCHEMA_REPRESENTATION)
    - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacityHistory#body.request_body.SCHEMA_REPRESENTATION.instance_properties.SCHEMA_REPRESENTATION)
- [Response body](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacityHistory#body.response_body)
  - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacityHistory#body.CapacityHistoryResponse.SCHEMA_REPRESENTATION)
    - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacityHistory#body.CapacityHistoryResponse.SCHEMA_REPRESENTATION.preemption_history.SCHEMA_REPRESENTATION)
    - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacityHistory#body.CapacityHistoryResponse.SCHEMA_REPRESENTATION.price_history.SCHEMA_REPRESENTATION)
    - [JSON representation](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacityHistory#body.CapacityHistoryResponse.SCHEMA_REPRESENTATION.price_history.SCHEMA_REPRESENTATION_1)
- [Authorization scopes](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacityHistory#body.aspect)
- [IAM Permissions](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacityHistory#body.aspect_1)
- [Try it!](https://docs.cloud.google.com/compute/docs/reference/rest/v1/advice/capacityHistory#try-it)

Gets the capacity history.

### 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/capacityHistory`

<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": { "machineType": string, "scheduling": { "provisioningModel": enum } }, "locationPolicy": { "location": string }, "types": [ enum ] } ``` |

| Fields ||
|---|---|
| `instanceProperties.machineType` | `string` The machine type for the VM, such as `n2-standard-4`. |
| `instanceProperties.scheduling` | `object` Specifies the scheduling options. |
| `instanceProperties.scheduling.provisioningModel` | `enum` The provisioning model to get capacity history for. This field must be set to `SPOT`. For more information, see [Compute Engine instances provisioning models](https://docs.cloud.google.com/compute/docs/instances/provisioning-models). |
| `locationPolicy` | `object` Location policy for this request. |
| `locationPolicy.location` | `string` The region or zone to get capacity history for. 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 /> This field is optional. |
| `types[]` | `enum` List of history types to get capacity history for. |

### Response body

Contains the capacity history.

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

| JSON representation |
|---|
| ``` { "machineType": string, "location": string, "preemptionHistory": [ { "interval": { "startTime": string, "endTime": string }, "preemptionRate": number } ], "priceHistory": [ { "interval": { "startTime": string, "endTime": string }, "listPrice": { "currencyCode": string, "units": string, "nanos": integer } } ] } ``` |

| Fields ||
|---|---|
| `machineType` | `string` The machine type for which the capacity history is returned. |
| `location` | `string` Output only. The location (region or zone) for which the capacity history is returned. It is returned as a URL - For example, `https://www.googleapis.com/compute/v1/projects/project/zones/zone`. |
| `preemptionHistory[]` | `object` The preemption history for the requested machine type and location. |
| `preemptionHistory[].interval` | `object` The time interval for this preemption record. |
| `preemptionHistory[].interval.startTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start. 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"`. |
| `preemptionHistory[].interval.endTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end. 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"`. |
| `preemptionHistory[].preemptionRate` | `number` The preemption rate during the interval, representing the fraction of Spot VMs that were preempted. Range: 0.0 to 1.0. Preemption rate is calculated as `(total preempted Spots) / (total Spots that stopped running)`. |
| `priceHistory[]` | `object` The price history for the requested machine type and location. |
| `priceHistory[].interval` | `object` The time interval for this price record. |
| `priceHistory[].interval.startTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start. 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"`. |
| `priceHistory[].interval.endTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end. 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"`. |
| `priceHistory[].listPrice` | `object` The Spot VM list price during the interval. |
| `priceHistory[].listPrice.currencyCode` | `string` The three-letter currency code defined in ISO 4217. |
| `priceHistory[].listPrice.units` | `string (https://developers.google.com/discovery/v1/type-format format)` The whole units of the amount. For example if `currencyCode` is `"USD"`, then 1 unit is one US dollar. |
| `priceHistory[].listPrice.nanos` | `integer` Number of nano (10\^-9) units of the amount. The value must be between -999,999,999 and +999,999,999 inclusive. If `units` is positive, `nanos` must be positive or zero. If `units` is zero, `nanos` can be positive, zero, or negative. If `units` is negative, `nanos` must be negative or zero. For example $-1.75 is represented as `units`=-1 and `nanos`=-750,000,000. |

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

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