View reservations or future reservation requests

This document explains how to view your reservations, future reservationrequests, and reservation consumption. To learn more about reservations, seeChoose a reservation type.

When you view your reservations, future reservation requests, or reservationconsumption, you can do the following:

View reservation settings. This review helps you verify the details ofyour reservations, ensure that they meet your needs, and plan for capacity.
Determine the number of consumable instances. This check helps youdetermine how many Compute Engine instances can consume your reservedcapacity.
View reservation consumption. This review lets you verify whichreservation a specific Compute Engine instance is consuming, or listall instances that are consuming a particular reservation within aproject.

Limitations

You can only view a shared reservation or shared future reservation request inthe project where you created it.

Before you begin

If you haven't already, set upauthentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
1. Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:
  gcloudinit
  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.
2. Set a default region and zone.
Go
To use the Go samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
For more information, see Set up authentication for a local development environment.
Java
To use the Java samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
For more information, see Set up authentication for a local development environment.
Node.js
To use the Node.js samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
For more information, see Set up authentication for a local development environment.
Python
To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
For more information, see Set up authentication for a local development environment.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Required roles

To get the permissions that you need to view reservations or future reservation requests, ask your administrator to grant you theCompute Admin (roles/compute.admin) IAM role on the project. For more information about granting roles, seeManage access to projects, folders, and organizations.

This predefined role contains the permissions required to view reservations or future reservation requests. To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

The following permissions are required to view reservations or future reservation requests:

To view a list of reservations: compute.reservations.list on the project
To view a list of future reservation requests: compute.futureReservations.list on the project
To view the details of a reservation: compute.reservations.get on the project
To view the details of a future reservation request: compute.futureReservations.get on the project

You might also be able to get these permissions withcustom roles or otherpredefined roles.

View reservation settings

The following sections explain how to view the settings of your reservations orfuture reservation requests.

View reservations

To view the settings of one or more reservations, use one of the followingmethods described in this section:

To view an overview of all reservations in your project, view a list of yourreservations.
To view the full details of a single reservation, view the details of thereservation.

To view thedeleteAtTime andreservationSharingPolicy fields(Preview) in a reservation, view the detailsof a reservation using the Google Cloud CLI, or view reservations using theREST API. If you don't require these fields, then view reservations byselecting any of the following options:

Console

In the Google Cloud console, go to theReservations page.
Go to Reservations
On theOn-demand reservations tab (default), the table lists eachreservation, and each table column describes a property.
Optional: In theOn-demand reservations table, do one or both of thefollowing:
- To display theassured count ofyour reservations, clickColumn display options..., select theAssured countcheckbox, and then clickOK.
- To refine your list of reservations, in theFilter field,select the properties that you want to filter the reservations by.
To view the details of a reservation, in theName column, click thename of the reservation. A page that gives the details of thereservation opens.

gcloud

To view a list of your reservations, use thegcloud compute reservations list command:
```
gcloud compute reservations list
```
The output is similar to the following example:
```
NAME: r-01IN_USE_COUNT: 0COUNT: 5ZONE: us-central1-aSHARE_TYPE: LOCALNAME: r-02IN_USE_COUNT: 3COUNT: 10ZONE: us-central1-fSHARE_TYPE: LOCAL
```
Optionally, to refine a list of reservations using afilter expression,include the--filter flag:
```
gcloud compute reservations list \    --filter="FILTER_EXPRESSION"
```
ReplaceFILTER_EXPRESSION with a filter expression.

To view the details of a reservation, use thegcloud compute reservations describe command:

Note: To view thedeleteAtTime andreservationSharingPolicy fieldsin a reservation, use the gcloud beta compute reservations describe command.

gcloud compute reservations describeRESERVATION_NAME \    --zone=ZONE

Replace the following:

RESERVATION_NAME: the name of an existingreservation.
ZONE: the zone where the reservation exists.

The output is similar to the following example:

creationTimestamp: '2024-10-11T03:25:23.192-07:00'id: '4488228526648280060'kind: compute#reservationname: r-01selfLink: https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/r-01shareSettings:  shareType: LOCALspecificReservation:  assuredCount: '50'  count: '50'  inUseCount: '25'  instanceProperties:    machineType: n2-standard-2specificReservationRequired: falsestatus: READYzone: https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a

Go

To view a list of your reservations, use the following code sample:

// Copyright 2024 Google LLC//// Licensed under the Apache License, Version 2.0 (the "License");// you may not use this file except in compliance with the License.// You may obtain a copy of the License at////     https://www.apache.org/licenses/LICENSE-2.0//// Unless required by applicable law or agreed to in writing, software// distributed under the License is distributed on an "AS IS" BASIS,// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.// See the License for the specific language governing permissions and// limitations under the License.packagesnippetsimport("context""fmt""io"compute"cloud.google.com/go/compute/apiv1"computepb"cloud.google.com/go/compute/apiv1/computepb""google.golang.org/api/iterator")// Get list of reservations for given project in particular zonefunclistReservations(wio.Writer,projectID,zonestring)error{// projectID := "your_project_id"// zone := "us-west3-a"ctx:=context.Background()reservationsClient,err:=compute.NewReservationsRESTClient(ctx)iferr!=nil{returnerr}deferreservationsClient.Close()req:=&computepb.ListReservationsRequest{Project:projectID,Zone:zone,}it:=reservationsClient.List(ctx,req)fmt.Fprintf(w,"Instances found in zone %s:\n",zone)for{instance,err:=it.Next()iferr==iterator.Done{break}iferr!=nil{returnerr}fmt.Fprintf(w,"- %s %d\n",instance.GetName(),instance.GetSpecificReservation().GetCount())}returnnil}

To view the details of a reservation, use the following code sample:

// Copyright 2024 Google LLC//// Licensed under the Apache License, Version 2.0 (the "License");// you may not use this file except in compliance with the License.// You may obtain a copy of the License at////     https://www.apache.org/licenses/LICENSE-2.0//// Unless required by applicable law or agreed to in writing, software// distributed under the License is distributed on an "AS IS" BASIS,// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.// See the License for the specific language governing permissions and// limitations under the License.packagesnippetsimport("context""fmt""io"compute"cloud.google.com/go/compute/apiv1"computepb"cloud.google.com/go/compute/apiv1/computepb")// Get certain reservation for given project and zonefuncgetReservation(wio.Writer,projectID,zone,reservationNamestring)(*computepb.Reservation,error){// projectID := "your_project_id"// zone := "us-west3-a"// reservationName := "your_reservation_name"ctx:=context.Background()reservationsClient,err:=compute.NewReservationsRESTClient(ctx)iferr!=nil{returnnil,err}deferreservationsClient.Close()req:=&computepb.GetReservationRequest{Project:projectID,Reservation:reservationName,Zone:zone,}reservation,err:=reservationsClient.Get(ctx,req)iferr!=nil{returnnil,fmt.Errorf("unable to delete reservation: %w",err)}fmt.Fprintf(w,"Reservation: %s\n",reservation.GetName())returnreservation,nil}

Java

To view a list of your reservations, use the following code sample:

/* * Copyright 2024 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * *   http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */packagecompute.reservation;importcom.google.cloud.compute.v1.Reservation;importcom.google.cloud.compute.v1.ReservationsClient;importjava.io.IOException;importjava.util.ArrayList;importjava.util.List;publicclassListReservations{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace these variables before running the sample.// Project ID or project number of the Cloud project you want to use.Stringproject="YOUR_PROJECT_ID";// Zone in which reservations are located.Stringzone="us-central1-a";listReservations(project,zone);}// List all reservations in the given project and zone.publicstaticList<Reservation>listReservations(Stringproject,Stringzone)throwsIOException{// Initialize client that will be used to send requests. This client only needs to be created// once, and can be reused for multiple requests.List<Reservation>listOfReservations=newArrayList<>();try(ReservationsClientreservationsClient=ReservationsClient.create()){for(Reservationreservation:reservationsClient.list(project,zone).iterateAll()){listOfReservations.add(reservation);System.out.println("Reservation: "+reservation.getName());}}returnlistOfReservations;}}

To view the details of a reservation, use the following code sample:

/* * Copyright 2024 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */packagecompute.reservation;importcom.google.cloud.compute.v1.Reservation;importcom.google.cloud.compute.v1.ReservationsClient;importjava.io.IOException;importjava.util.concurrent.ExecutionException;importjava.util.concurrent.TimeoutException;publicclassGetReservation{publicstaticvoidmain(String[]args)throwsIOException,ExecutionException,InterruptedException,TimeoutException{// TODO(developer): Replace these variables before running the sample.// Project ID or project number of the Cloud project you want to use.StringprojectId="YOUR_PROJECT_ID";// Name of the zone in which you want to create the reservation.Stringzone="us-central1-a";// Name of the reservation you want to create.StringreservationName="test-reservation-name";getReservation(projectId,reservationName,zone);}// Retrieve a reservation with the given name in the given zone.publicstaticReservationgetReservation(StringprojectId,StringreservationName,Stringzone)throwsIOException{// Initialize client that will be used to send requests. This client only needs to be created// once, and can be reused for multiple requests.try(ReservationsClientreservationsClient=ReservationsClient.create()){// Get the reservation.Reservationreservation=reservationsClient.get(projectId,zone,reservationName);System.out.println("Reservation: "+reservation.getName());returnreservation;}}}

Node.js

To view a list of your reservations, use the following code sample:

/* * Copyright 2024 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * *     https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */'use strict';asyncfunctionmain(){// Import the Compute libraryconstcomputeLib=require('@google-cloud/compute');// Instantiate a reservationsClientconstreservationsClient=newcomputeLib.ReservationsClient();/**   * TODO(developer): Update these variables before running the sample.   */// The ID of the project where your reservations are located.constprojectId=awaitreservationsClient.getProjectId();// The zone where your reservations are located.constzone='us-central1-a';asyncfunctioncallGetReservations(){constreservations=(awaitreservationsClient.list({project:projectId,zone,}))[0];console.log(JSON.stringify(reservations));}awaitcallGetReservations();}main().catch(err=>{console.error(err);process.exitCode=1;});

To view the details of a reservation, use the following code sample:

/* * Copyright 2024 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * *     https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */'use strict';asyncfunctionmain(reservationName){// Import the Compute libraryconstcomputeLib=require('@google-cloud/compute');// Instantiate a reservationsClientconstreservationsClient=newcomputeLib.ReservationsClient();/**   * TODO(developer): Update/uncomment these variables before running the sample.   */// The ID of the project where your reservation is located.constprojectId=awaitreservationsClient.getProjectId();// The zone where your reservation is located.constzone='us-central1-a';// The name of the reservation to return.// reservationName = 'reservation-01';asyncfunctioncallGetReservation(){constrequestedReservation=(awaitreservationsClient.get({project:projectId,zone,reservation:reservationName,}))[0];console.log(JSON.stringify(requestedReservation));}awaitcallGetReservation();}main(...process.argv.slice(2)).catch(err=>{console.error(err);process.exitCode=1;});

Python

To view a list of your reservations, use the following code sample:

# Copyright 2024 Google LLC## Licensed under the Apache License, Version 2.0 (the "License");# you may not use this file except in compliance with the License.# You may obtain a copy of the License at##    https://www.apache.org/licenses/LICENSE-2.0## Unless required by applicable law or agreed to in writing, software# distributed under the License is distributed on an "AS IS" BASIS,# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.# See the License for the specific language governing permissions and# limitations under the License.# This file is automatically generated. Please do not modify it directly.# Find the relevant recipe file in the samples/recipes or samples/ingredients# directory and apply your changes there.fromgoogle.cloudimportcompute_v1fromgoogle.cloud.compute_v1.services.reservations.pagersimportListPagerdeflist_compute_reservation(project_id:str,zone:str="us-central1-a")->ListPager:"""    Lists all compute reservations in a specified Google Cloud project and zone.    Args:        project_id (str): The ID of the Google Cloud project.        zone (str): The zone of the reservations.    Returns:        ListPager: A pager object containing the list of reservations.    """client=compute_v1.ReservationsClient()reservations_list=client.list(project=project_id,zone=zone,)forreservationinreservations_list:print("Name: ",reservation.name)print("Machine type: ",reservation.specific_reservation.instance_properties.machine_type,)# Example response:# Name:  my-reservation_1# Machine type:  n1-standard-1# Name:  my-reservation_2# Machine type:  n1-standard-1returnreservations_list

To view the details of a reservation, use the following code sample:

# Copyright 2024 Google LLC## Licensed under the Apache License, Version 2.0 (the "License");# you may not use this file except in compliance with the License.# You may obtain a copy of the License at##    https://www.apache.org/licenses/LICENSE-2.0## Unless required by applicable law or agreed to in writing, software# distributed under the License is distributed on an "AS IS" BASIS,# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.# See the License for the specific language governing permissions and# limitations under the License.# This file is automatically generated. Please do not modify it directly.# Find the relevant recipe file in the samples/recipes or samples/ingredients# directory and apply your changes there.fromgoogle.cloudimportcompute_v1fromgoogle.cloud.compute_v1.typesimportcomputedefget_compute_reservation(project_id:str,zone:str="us-central1-a",reservation_name="your-reservation-name",)->compute.Reservation:"""    Retrieves a compute reservation from GCP.    Args:        project_id (str): The ID of the Google Cloud project.        zone (str): The zone of the reservation.        reservation_name (str): The name of the reservation to retrieve.    Returns:        compute.Reservation: The reservation object retrieved from Google Cloud.    """client=compute_v1.ReservationsClient()reservation=client.get(project=project_id,zone=zone,reservation=reservation_name,)print("Name: ",reservation.name)print("STATUS: ",reservation.status)print(reservation.specific_reservation)# Example response:# Name:  your-reservation-name# STATUS:  READY# count: 3# instance_properties {#   machine_type: "n1-standard-1"#   local_ssds {#     disk_size_gb: 375#     interface: "NVME"#   }# ...returnreservation

REST

To view a list of your reservations, make aGET request to thereservations.list method:

Note: To view thedeleteAtTime andreservationSharingPolicy fieldsin your reservations, make aGET request to the betareservations.list method.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations

Replace the following:

PROJECT_ID: the ID of the project where you createdyour reservations.
ZONE: the zone where your reservations exist.

The output is similar to the following example:

{  "kind": "compute#reservation",  "id": "4100668622331754141",  "creationTimestamp": "2019-09-27T08:21:14.707-07:00",  "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/reservation-05",  "zone": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a",  "name": "reservation-05",  "specificReservation": {    "instanceProperties": {      "machineType": "n1-standard-2"    },    "count": "100",    "inUseCount": "0",    "assuredCount": "100"  },  "specificReservationRequired": false,  "status": "READY",  "shareSettings": {    "shareType": "LOCAL"  }},{  "kind": "compute#reservation",  "id": "2533514314332214789",  "creationTimestamp": "2019-09-27T08:21:14.707-07:00",  "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/reservation-04",  "zone": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a",  "name": "reservation-04",  "specificReservation": {    "instanceProperties": {      "machineType": "n1-standard-2",      "guestAccelerators": [        {          "acceleratorType": "nvidia-tesla-t4",          "acceleratorCount": 1        }      ],      "localSsds": [        {          "diskSizeGb": "375",          "interface": "SCSI"        }      ]    },    "count": "50",    "inUseCount": "25",    "assuredCount": "50"  },  "specificReservationRequired": false,  "status": "READY",  "shareSettings": {    "shareType": "LOCAL"  }}

Optionally, to refine a list of reservations using afilter expression,include thefilter query parameter:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations?filter=FILTER_EXPRESSION

ReplaceFILTER_EXPRESSION with a filter expressionthat usesURL-encoded values.

To view the details of a reservation, make aGET request to thereservations.get method.

Note: To view thedeleteAtTime andreservationSharingPolicy fieldsin a reservation, make aGET request to the beta.reservations.get method.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME

Replace the following:

PROJECT_ID: the ID of the project where youcreated the reservation.
ZONE: the zone where the reservation exists.
RESERVATION_NAME: the name of an existingreservation.

The output is similar to the following example:

{  "kind": "compute#reservation",  "id": "4488228526648280060",  "creationTimestamp": "2024-10-11T03:25:23.192-07:00",  "selfLink": "https://www.googleapis.com/compute/v1/projects/davide-experimental/zones/us-central1-a/reservations/r-01",  "zone": "https://www.googleapis.com/compute/v1/projects/davide-experimental/zones/us-central1-a",  "name": "r-01",  "specificReservation": {    "instanceProperties": {      "machineType": "n2-standard-2"    },    "count": "50",    "inUseCount": "25",    "assuredCount": "50"  },  "specificReservationRequired": false,  "status": "READY",  "shareSettings": {    "shareType": "LOCAL"  }}

View future reservation requests

To view the settings of one or more future reservation requests, use one of thefollowing methods described in this section:

To view an overview of all future reservation requests in your project, viewa list of your requests.
To view the full details of a single future reservation request, view thedetails of the request.

To view future reservation requests, select one of the following options:

Console

In the Google Cloud console, go to theReservations page.
Go to Reservations
Click theFuture reservations tab.
The table lists each future reservation request, and each table columndescribes a property.
Optional: To refine your list of requests, in theFilter field, selectthe properties that you want to filter the requests by.
To view the details of a request, in theName column, click the nameof the request. A page that gives the details of the future reservationrequest opens.

gcloud

To view a list of your future reservation requests, use thegcloud compute future-reservations list command:

gcloud compute future-reservations list

The output is similar to the following example:

NAME: fr-04TOTAL_COUNT: 100START_TIME: 2025-07-20T07:00:00ZEND_TIME: 2025-08-05T07:00:00ZPROCUREMENT_STATUS: FULFILLEDZONE: us-east1-aNAME: fr-05TOTAL_COUNT: 10START_TIME: 2025-07-20T07:00:00ZEND_TIME: 2025-12-01T00:00:00ZPROCUREMENT_STATUS: PENDING_APPROVALZONE: us-west1-c

Optionally, to refine a list of future reservation requests using afilter expression,include the--filter flag:

gcloud compute future-reservations list \    --filter="FILTER_EXPRESSION"

ReplaceFILTER_EXPRESSION with a filter expression.

To view the details of a future reservation request, use thegcloud compute future-reservations describe command:

gcloud compute future-reservations describeFUTURE_RESERVATION_NAME \    --zone=ZONE

Replace the following:

FUTURE_RESERVATION_NAME: the name of an existingfuture reservation request.
ZONE: the zone where the future reservationrequest exists.

The output is similar to the following example:

autoCreatedReservationsDeleteTime: '2025-05-02T01:00:00Z'creationTimestamp: '2025-03-23T10:08:31.613-07:00'id: '5212276518668495076'kind: compute#futureReservationname: fr-01planningStatus: SUBMITTEDselfLink: https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/futureReservations/fr-01selfLinkWithId: https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/futureReservations/5212276518668495076shareSettings:  shareType: LOCALspecificSkuProperties:  instanceProperties:    machineType: n1-standard-64  totalCount: '800'status:  existingMatchingUsageInfo:    count: '3'    timestamp: '2025-03-30T01:00:00Z'  lockTime: '2025-03-30T17:09:59.297799Z'  procurementStatus: APPROVEDtimeWindow:  endTime: '2025-05-02T01:00:00Z'  startTime: '2025-04-30T17:30:00Z'zone: https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a

REST

To view a list of your future reservation requests, make aGETrequest to thefutureReservations.list method:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/futureReservations

Replace the following:

PROJECT_ID: the ID of the project where youcreated your future reservation requests.
ZONE: the zone where your future reservationrequests exist.

The output is similar to the following example:

{  "id": "projects/my-project/zones/us-east1-a/futureReservations",  "items": [    {      "id": "743865190848184978",      "creationTimestamp": "2025-03-23T18:16:45.274-07:00",      "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-east1-a/futureReservations/fr-base",      "selfLinkWithId": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-east1-a/futureReservations/743865190848184978",      "zone": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-east1-a",      "name": "fr-base",      "specificSkuProperties": {        "instanceProperties": {          "machineType": "n1-standard-1"        },        "totalCount": "100"      },      "planningStatus": "SUBMITTED",      "timeWindow": {        "endTime": "2025-05-02T01:00:00Z",        "startTime": "2025-04-30T17:30:00Z"      },      "status": {        "procurementStatus": "FULFILLED",        "lockTime": "2025-03-30T07:00:00Z",        "existingMatchingUsageInfo": {          "count": "3",          "timestamp": "2025-03-30T01:00:00Z"        }      },      "kind": "compute#futureReservation"    },    ...  ],  "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-east1-a/futureReservations",  "etag": "AnzKY34l-cvvV-JnniESJ0dtQvQ=/hvc4jaHpxFAZmOt1FVtKNgzZu-M=",  "kind": "compute#futureReservationsListResponse"}

Optionally, to refine a list of future reservation requests using afilter expression,include thefilter query parameter:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/aggregated/futureReservations?filter=FILTER_EXPRESSION

ReplaceFILTER_EXPRESSION with a filter expressionthat usesURL-encoded values.

To view the details of a future reservation request, make aGETrequest to thefutureReservations.get method:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/futureReservations/FUTURE_RESERVATION_NAME

Replace the following:

PROJECT_ID: the ID of the project where youcreated the future reservation request.
ZONE: the zone where the future reservationrequest exists.
FUTURE_RESERVATION_NAME: the name of an existingfuture reservation request.

The output is similar to the following:

{  "autoCreatedReservationsDeleteTime": "2025-05-02T01:00:00Z",  "creationTimestamp": "2025-03-23T10:08:31.613-07:00",  "id": "5212276518668495076",  "kind": "compute#futureReservation",  "name": "fr-01",  "planningStatus": "SUBMITTED",  "selfLink": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/futureReservations/fr-01",  "selfLinkWithId": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/futureReservations/5212276518668495076",  "shareSettings": {    "shareType": "LOCAL"  },  "specificSkuProperties": {    "instanceProperties": {      "machineType": "n1-standard-64"    },    "totalCount": "800"  },  "status": {    "lockTime": "2025-03-30T17:09:59.297799Z",    "procurementStatus": "APPROVED",    "existingMatchingUsageInfo": {      "count": "3",      "timestamp": "2025-03-30T01:00:00Z"    }  },  "timeWindow": {    "endTime": "2025-05-02T01:00:00Z",    "startTime": "2025-04-30T17:30:00Z"  },  "zone": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a"}

Determine the number of consumable instances

To determine the number of compute instances that can consume your reservedcapacity, do one of the following:

To view the maximum number of instances that can consume a reservation, seeConsumable instances in a reservation.
To view the number of instances that Compute Engine is set toreserve for a future reservation request at the request start time, seeConsumable instances in a future reservation request.
To view the number of instances that Compute Engine is set toreserve for a future reservation request in calendar mode at the requeststart time, seeConsumable instances in a future reservation request in calendar mode.

Consumable instances in a reservation

When youview the details of a reservation, you can viewhow many compute instances are consuming the reservation, and how many instancescan consume it, by checking the following fields:

Assured count (assuredCount): the number of instances that arephysically reserved within the zone of the reservation. This number includesthe instances reserved for your project, and for any project a sharedreservation is shared with.
Total count (count): the number of reserved instances specified in thereservation. This number should match the assured count.
Caution: If the assured count is lower than the total count, then fewerinstances than expected are reserved. To troubleshoot this issue, see Fewer VMs available for consumption.
Machines in use (inUseCount): the number of running instances in yourproject, or a project a shared reservation is shared with, that areconsuming the reservation.

For example, if the assured count (assuredCount) and total count (count) areboth 50, and the number of instances consuming the reservation (inUseCount) is25, then 25 more instances can consume the reservation before it's fullyconsumed.

Consumable instances in a future reservation request

You can determine the number of compute instances for whichCompute Engine creates a reservation at a future reservation requeststart time. For a draft, pending approval, or approved request, you candetermine this number as follows:

View how many running instances and unused reservations in your project, andin any project the request is shared with, match the request properties.
Subtract the number of matching running instances and unused reservationsfrom thetotal countin the request.

You can determine the number of consumable instances for single or multiplerequests at once. For multiple requests, use the Google Cloud console orREST API. For single requests, select any of the following options:

Console

In the Google Cloud console, go to theReservations page.
Go to Reservations
Click theFuture reservations tab.
The table lists each future reservation request, and each table columndescribes a property.
To determine the number of instances that Compute Engine plansto reserve for a request at its start time, subtract theMatching count column from theTotal count column.
TheMatching count column shows one of the following warnings:
- Matching count is zero: there are no matching running instancesor unused reservations in your project, or in any project that yourrequest is shared with.
- Matching count equals Total count: Compute Engine won'treserve any instances for your request at its star time.
If youmodify a request,or create new instances or reservations that match the request, thenCompute Engine updates theMatching count column within 30minutes.
Optional: To check when theMatching count column was last updatedin a request, do the following:
1. In theName column, click the name of the request. A page thatgives the details of the future reservation request opens.
2. In theResource details section, check theLast matching usage evaluation time field.

gcloud

To view the details of a future reservation request, use thegcloud compute future-reservations describe command:
```
gcloud compute future-reservations describeFUTURE_RESERVATION_NAME \    --zone=ZONE
```
Replace the following:
- FUTURE_RESERVATION_NAME: the name of an existingfuture reservation request.
- ZONE: the zone where the future reservationrequest exists.
In the output, find thecount andtotalCount fields:
```
...specificSkuProperties:  ...totalCount: '100'status:  existingMatchingUsageInfo:count: '50'    timestamp: '2025-03-30T01:00:00Z'  ...  procurementStatus: DRAFTING...
```
Subtract the value ofcount fromtotalCount. For example, ifcountis 50 andtotalCount is 100, then Compute Engine automaticallycreates a reservation for 50 instances at the request start time.
If youmodify the request,or create new instances or reservations that match the request, thenCompute Engine updates theexistingMatchingUsageInfo fieldwithin 30 minutes. To verify when this field was last updated, check thevalue ofexistingMatchingUsageInfo.timestamp.

REST

To view a list of your future reservation requests, make aGET requestto thefutureReservations.list method.In the request URL, include thefilter query parameter and specify toshow only thename,specificSkuProperties, andstatus fields:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/futureReservations?fields=items.name,items.specificSkuProperties,items.status

Replace the following:

PROJECT_ID: the ID of the project where youcreated your future reservation requests.
ZONE: the zone where the future reservationrequest exists.

In the output, find thecount andtotalCount fields for each draft,pending approval, or approved request:

{  "items": [    {      "specificSkuProperties": {        ...totalCount: "100"      },      "name": "fr-01",      "status": {        "procurementStatus": "APPROVED",        ...        existingMatchingUsageInfo: {count: "50",          "timestamp": "2025-01-22T07:54:26.295Z"        }      }    },    {      "specificSkuProperties": {        ...totalCount: "20"      },      "name": "fr-02",      "status": {        "procurementStatus": "DRAFTING",        ...        existingMatchingUsageInfo: {"count": "2",          "timestamp": "2025-01-22T07:54:26.295Z"        }      }    }  ]}

For each request, subtract the value ofcount fromtotalCount. Forexample, ifcount is 50 andtotalCount is 100, thenCompute Engine automatically creates a reservation for 50instances at the request start time.
If youmodify a request,or create new instances or reservations that match the request, thenCompute Engine updates theexistingMatchingUsageInfo fieldwithin 30 minutes. To verify when this field was last updated, check thevalue ofexistingMatchingUsageInfo.timestamp.

Consumable instances in a future reservation request in calendar mode

When youview the details of a future reservation request,you can see how many compute instances Compute Engine plans to provisionat the request start time. Compute Engine creates the number ofinstances specified in the request, regardless of the number of matchinginstances in your project or in any project that the request is shared with.

View reservation consumption

Whenever a compute instance consumes a reservation, you can view the following:

View the reservation that an instance is consuming

To view the reservation that an instance is consuming, select one of thefollowing options:

Console

In the Google Cloud console, go to theVM instances page.
Go to VM instances
Click the name of the instance that is consuming a reservation thatyou want to view.
In theBasic information section, theConsumed reservation fieldshows the name of the reservation that the instance is consuming.

gcloud

To view the reservation that an instance is consuming, use thegcloud compute instances describe commandwith the--flatten=resourceStatus.reservationConsumptionInfo flag:

gcloud compute instances describeINSTANCE_NAME \    --flatten=resourceStatus.reservationConsumptionInfo \    --zone=ZONE

Replace the following:

INSTANCE_NAME: the name of the instance.
ZONE: the zone where the instance exists.

You see an output that is similar to the following:

consumedReservation: https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c/reservations/example-reservation

REST

To view the reservation that an instance is consuming, make aGET requestto theinstances.get method.In the request URL, include thefields query parameter set toresourceStatus.reservationConsumptionInfo:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/var>/zones/ZONE/instances/INSTANCE_NAME?fields=resourceStatus.reservationConsumptionInfo

Replace the following:

PROJECT_ID: the ID of the project in which the instance exists.
ZONE: the zone where the instance exists.
INSTANCE_NAME: the name of the instance.

You see a response that is similar to the following:

{  "resourceStatus": {    "reservationConsumptionInfo": {      "consumedReservation": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations/example-reservation"    }  }}

View a list of instances that are consuming a reservation

You can view a list of instances consuming a reservation within a singleproject. Forshared reservations,this method returns only the instances in the project that you specify; itdoesn't include instances from other consumer projects that are consuming thesame reservation.

To view the instances that are consuming a reservation, select one of thefollowing options:

gcloud

To view the instances that are consuming a reservation, use thegcloud compute instances list commandwith the--filter flag set to the reservation that you want to view:

gcloud compute instances list \    --project=CONSUMER_PROJECT_ID \    --zones=ZONE \    --filter="resourceStatus.reservationConsumptionInfo.consumedReservation:https://www.googleapis.com/compute/v1/projects/HOST_PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME"

Replace the following:

CONSUMER_PROJECT_ID: the ID of the project consumingthe reservation.
ZONE: the zone where the reservation and theinstances are located.
HOST_PROJECT_ID: the ID of the project where thereservation was created (if different from the consumer project).
RESERVATION_NAME: the name of the reservation.

You see an output that is similar to the following:

NAME               ZONE           MACHINE_TYPE  PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP     STATUSmy-e2-instance     us-central1-c  e2-medium                  10.128.0.61  35.239.208.172  RUNNINGmy-e2-instance-02  us-central1-c  e2-medium                  10.128.0.62  104.154.31.123  RUNNINGmy-e2-instance-03  us-central1-c  e2-medium                  10.128.0.63  34.171.90.254   RUNNING

REST

To view the instances that are consuming a reservation, make aGET requestto theinstances.list method.In the request URL, include thefilter query parameter set to the name ofthe reservation that you want to view:

GET https://compute.googleapis.com/compute/v1/projects/CONSUMER_PROJECT_ID/zones/ZONE/instances?filter=resourceStatus.reservationConsumptionInfo.consumedReservation%3D%22.*%2Fprojects%2FHOST_PROJECT_ID%2Fzones%2FZONE%2Freservations%2FRESERVATION_NAME%22

Replace the following:

CONSUMER_PROJECT_ID: the ID of the project consumingthe reservation.
ZONE: the zone where the reservation and theinstances are located.
HOST_PROJECT_ID: the ID of the project where thereservation was created (if different from the consumer project).
RESERVATION_NAME: the name of the reservation.

You see a response that is similar to the following:

{  "kind": "compute#instanceList",  "id": "projects/example-project/zones/us-central1-a/instances",  "items": [    {      ...      "name": "example-instance-01",      ...      "resourceStatus": {        "scheduling": {},        "reservationConsumptionInfo": {          "consumedReservation": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations/example-reservation"        }      }    },    {      ...      "name": "example-instance-02",      ...      "resourceStatus": {        "scheduling": {},        "reservationConsumptionInfo": {          "consumedReservation": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations/example-reservation"        }      },      ...    }  ],  "selfLink": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/instances"}

What's next

Learn how toattach reservations to commitments.
Learn how toconsume reservations.
Learn how tomodify reservations.
Learn how todelete reservations.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-17 UTC.

Movatterモバイル変換

View reservations or future reservation requests Stay organized with collections Save and categorize content based on your preferences.

Limitations

Before you begin

Console

gcloud

Go

Java

Node.js

Python

REST

Required roles

Required permissions

View reservation settings

View reservations

Console

gcloud

Go

Java

Node.js

Python

REST

View future reservation requests

Console

gcloud

REST

Determine the number of consumable instances

Consumable instances in a reservation

Consumable instances in a future reservation request

Console

gcloud

REST

Consumable instances in a future reservation request in calendar mode

View reservation consumption

View the reservation that an instance is consuming

Console

gcloud

REST

View a list of instances that are consuming a reservation

gcloud

REST

What's next

View reservations or future reservation requests