---
title: "POST /projects/{project}/regions/{region}/advice/capacityHistory"
method: POST
path: "/projects/{project}/regions/{region}/advice/capacityHistory"
tags: ["advice"]
---

# POST /projects/{project}/regions/{region}/advice/capacityHistory

`POST /projects/{project}/regions/{region}/advice/capacityHistory`

## Request

- Base URL: `https://compute.googleapis.com/compute/v1`
- URL: `https://compute.googleapis.com/compute/v1/projects/{project}/regions/{region}/advice/capacityHistory`
- Auth: one of:
  - OAuth 2 and OAuth 2
    - Implicit: `https://accounts.google.com/o/oauth2/auth`
    - Scopes: `https://www.googleapis.com/auth/cloud-platform`
    - Authorization code: `https://accounts.google.com/o/oauth2/auth`
    - Token URL: `https://accounts.google.com/o/oauth2/token` scopes: `https://www.googleapis.com/auth/cloud-platform`
  - OAuth 2 and OAuth 2
    - Implicit: `https://accounts.google.com/o/oauth2/auth`
    - Scopes: `https://www.googleapis.com/auth/compute`
    - Authorization code: `https://accounts.google.com/o/oauth2/auth`
    - Token URL: `https://accounts.google.com/o/oauth2/token` scopes: `https://www.googleapis.com/auth/compute`

Gets the capacity history.

## Path parameters

- `project` string, required
- `region` string, required

## Request body

- CapacityHistoryRequest: A request to get the capacity history.
  - `instanceProperties` CapacityHistoryRequestInstanceProperties: Instance properties for this request.
    - `machineType` string: The machine type for the VM, such as `n2-standard-4`.
    - `scheduling` CapacityHistoryRequestInstancePropertiesScheduling: Scheduling options.
      - `provisioningModel` 'FLEX_START' | 'RESERVATION_BOUND' | 'SPOT' | 'STANDARD': The provisioning model to get capacity history for. This field must be set to SPOT. For more information, see Compute Engine instances provisioning models.
  - `locationPolicy` CapacityHistoryRequestLocationPolicy: Location policy for this request.
    - `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 This field is optional.
  - `types` string[]: List of history types to get capacity history for.

## Response `200`

Successful response

- CapacityHistoryResponse: Contains the capacity history.
  - `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.
  - `machineType` string: The machine type for which the capacity history is returned.
  - `preemptionHistory` CapacityHistoryResponsePreemptionRecord[]: The preemption history for the requested machine type and location.
    - `interval` Interval: Represents a time interval, encoded as a Timestamp start (inclusive) and a Timestamp end (exclusive). The start must be less than or equal to the end. When the start equals the end, the interval is empty (matches no time). When both start and end are unspecified, the interval matches any time.
      - `endTime` string, google-datetime: Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end.
      - `startTime` string, google-datetime: Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start.
    - `preemptionRate` number, double: 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` CapacityHistoryResponsePriceRecord[]: The price history for the requested machine type and location.
    - `interval` Interval: Represents a time interval, encoded as a Timestamp start (inclusive) and a Timestamp end (exclusive). The start must be less than or equal to the end. When the start equals the end, the interval is empty (matches no time). When both start and end are unspecified, the interval matches any time.
      - `endTime` string, google-datetime: Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end.
      - `startTime` string, google-datetime: Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start.
    - `listPrice` Money: Represents an amount of money with its currency type.
      - `currencyCode` string: The three-letter currency code defined in ISO 4217.
      - `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.
      - `units` string, int64: The whole units of the amount. For example if `currencyCode` is `"USD"`, then 1 unit is one US dollar.

## Changes

- **2026-10-30** `8b85e897d3dc`: 4 info
  - the security scope `https://www.googleapis.com/auth/cloud-platform` was added to the endpoint's security scheme `Oauth2`
  - the security scope `https://www.googleapis.com/auth/cloud-platform` was added to the endpoint's security scheme `Oauth2c`
  - the security scope `https://www.googleapis.com/auth/compute` was removed from the endpoint's security scheme `Oauth2`
  - the security scope `https://www.googleapis.com/auth/compute` was removed from the endpoint's security scheme `Oauth2c`
- **2026-10-23** `48929bf89eeb`: 4 info
  - the security scope `https://www.googleapis.com/auth/cloud-platform` was added to the endpoint's security scheme `Oauth2`
  - the security scope `https://www.googleapis.com/auth/cloud-platform` was added to the endpoint's security scheme `Oauth2c`
  - the security scope `https://www.googleapis.com/auth/compute` was removed from the endpoint's security scheme `Oauth2`
  - the security scope `https://www.googleapis.com/auth/compute` was removed from the endpoint's security scheme `Oauth2c`
- **2026-10-10** `aca8b5925289`: 2 breaking, 4 info
  - removed the request body
  - removed the media type `*/*` for the response with the status `200`
  - the security scope `https://www.googleapis.com/auth/cloud-platform` was added to the endpoint's security scheme `Oauth2`
  - the security scope `https://www.googleapis.com/auth/cloud-platform` was added to the endpoint's security scheme `Oauth2c`
  - …2 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/google/apis/compute/changes/projects/:project/regions/:region/advice/capacityHistory/post.md)

---

[API](https://skmtc.dev/google/apis/compute.md) - [All operations](https://skmtc.dev/google/apis/compute/llms.txt) - [OpenAPI document](https://skmtc.dev/google/apis/compute/revisions/8b85e897d3dc?raw)