View future reservation requests

This document explains how to view future reservation requests.

Viewing future reservation requests is useful to get an overview of all the future reservation requests in your project, and to review the configuration details of a future reservation request. If you want to view a shared future reservation request, then you can only view it using the owner project.

To view the auto-created reservations provisioned for a future reservation, see View reservations.

Before you begin

If you haven't already, then set up authentication. Authentication is the process by which your identity is verified 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, then initialize it by running the following command:
  gcloud init
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.
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 future reservation requests, ask your administrator to grant you the Compute Future Reservation Viewer (roles/compute.futureReservationViewer) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations.

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

Required permissions

The following permissions are required to view future reservation requests:

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

You might also be able to get these permissions with custom roles or other predefined roles.

View your future reservation requests

Based on the details that you want to view in a future reservation request, use one of the following methods:

To view the name, reservation period, state, total count, and zone of all future reservation requests in your project, view a list of future reservation requests.
To view all the configuration details and properties of a single future reservation request, view the details of the future reservation request.

View a list of future reservation requests

When viewing a list of your future reservation requests, you can use filter expressions to narrow down your results. For more advanced filter expressions, use the gcloud CLI or REST.

To view a list of future reservation requests in your project, select one of the following options:

Console

In the Google Cloud console, go to the Reservations page.

Go to Reservations
Click the Future reservations tab.

In the table, each row describes a future reservation request and each column describes a property. For example, the Total count column describes the reserved capacity of each future reservation request.
Optional: To filter the future reservation requests displayed in the table, do one or both of the following:
- In the Filter field, enter a filter expression.
  
  For example, to only view the future reservation requests that were created in zone us-central1-a or which reserved more than 10 resources, specify the following expression:
```
Zone:us-central1-a OR Total Count>10
```
- Click Column display options, and then select the values that you want to filter the table by.

gcloud

To view a list of future reservation requests, use the gcloud beta compute future-reservations list command.

gcloud beta compute future-reservations list

The output is similar to the following:

NAME: fr-04
TOTAL_COUNT: 100
START_TIME: 2025-07-20T07:00:00Z
END_TIME: 2025-08-05T07:00:00Z
PROCUREMENT_STATUS: FULFILLED
ZONE: us-east1-a

NAME: fr-05
TOTAL_COUNT: 10
START_TIME: 2025-07-20T07:00:00Z
END_TIME: 2025-12-01T00:00:00Z
PROCUREMENT_STATUS: PENDING_APPROVAL
ZONE: us-west1-c

Optionally, to filter your future reservation requests based on a filter expression, include the --filter flag.

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

Replace FILTER_EXPRESSION with a filter expression.

For example, to only view future reservations that were created in zone us-central1-a, specify an n2-standard-4 machine type, and have a total count greater than 10, specify the following filter expression:

zone=us-central1-a AND specificSkuProperties.instanceProperties.machineType=n2-standard-4 AND specificSkuProperties.totalCount>10

REST

To view a list of future reservation requests, make a GET request to the beta.futureResevations.list method.

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

Replace the following:

PROJECT_ID: the ID of the project where one or more future reservation requests are located.
ZONE: the zone where one or more future reservation requests are located.

The output is similar to the following:

{
  "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/beta/projects/my-project/zones/us-east1-a/futureReservations/fr-base",
      "selfLinkWithId": "https://www.googleapis.com/compute/beta/projects/my-project/zones/us-east1-a/futureReservations/743865190848184978",
      "zone": "https://www.googleapis.com/compute/beta/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/beta/projects/my-project/zones/us-east1-a/futureReservations",
  "etag": "AnzKY34l-cvvV-JnniESJ0dtQvQ=/hvc4jaHpxFAZmOt1FVtKNgzZu-M=",
  "kind": "compute#futureReservationsListResponse"
}

Optionally, to filter your future reservation requests based on a filter expression, include the the filter query parameter.

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

Replace the following:

PROJECT_ID: the ID of the project where one or more future reservation requests are located.
FILTER_EXPRESSION: a filter expression that uses URL-encoding.

For example, to only view future reservations that were created in zone us-central1-a, reserved an n2-standard-4 machine type, and have a total count greater than ten, specify the following filter expression:
```
zone=us-central1-a%20AND%20specificSkuProperties.instanceProperties.machineType=n2-standard-4%20AND%20specificSkuProperties.totalCount%3E10
```
Note that the URL-encoded filter expression represents the following decoded filter expression:
```
zone=us-central1-a AND specificSkuProperties.instanceProperties.machineType=n2-standard-4 AND specificSkuProperties.totalCount>10
```

View the details of a future reservation request

To view the details of a future reservation request, select one of the following options:

Console

In the Google Cloud console, go to the Reservations page.

Go to Reservations
Click the Future reservations tab.
In the Name column, click the name of the future reservation request that you want to view the details of.

The Future reservations page with the details of the future reservation request opens.

gcloud

To view the details of a future reservation request, use the gcloud beta compute future-reservations describe command.

gcloud beta compute future-reservations describe FUTURE_RESERVATION_NAME \
    --zone=ZONE

Replace the following:

FUTURE_RESERVATION_NAME: the name of an existing future reservation request.
ZONE: the zone where the future reservation request is located.

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/beta/projects/example-project/zones/us-central1-a/futureReservations/fr-01
selfLinkWithId: https://www.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations/5212276518668495076
shareSettings:
  shareType: LOCAL
specificSkuProperties:
  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: APPROVED
timeWindow:
  endTime: '2025-05-02T01:00:00Z'
  startTime: '2025-04-30T17:30:00Z'
zone: https://www.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a

REST

To view the details of a future reservation request, make a GET request to the beta.futureReservations.get method.

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

Replace the following:

PROJECT_ID: the ID of the project where the future reservation request is located.
ZONE: the zone where the future reservation request is located.
FUTURE_RESERVATION_NAME: the name of an existing future 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/beta/projects/example-project/zones/us-central1-a/futureReservations/fr-01",
  "selfLinkWithId": "https://www.googleapis.com/compute/beta/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/beta/projects/example-project/zones/us-central1-a"
}

Determine the number of provisioned VMs

After you create a future reservation request, you can see how many running VMs and unused reservations in your project, or a project that the future reservation request is shared with, match the VM properties specified in your request. By subtracting this number from the total count specified in your request, you can determine how many VMs Compute Engine will provision after your request is approved and reaches its start time.

To determine the number of provisioned VMs for multiple future reservation requests simultaneously, use the Google Cloud console. Otherwise, to determine the number of provisioned VMs for a single request, select any of the following options:

Console

In the Google Cloud console, go to the Reservations page.

Go to Reservations
Click the Future reservations tab.
For each future reservation request, you can determine the following:
- In the Total count column, the request's total count.
- In the Matching count column, the number of running VMs and reservations which VM properties match the request.
By subtracting the value in the Matching count column from the value in the Total count column, you can determine the number of VMs that Compute Engine will provision for a future reservation request at its start time. If you see a warning in the Matching count column, then it's because of one of the following:
- The value of Matching count is zero. In this case, there are no matching running VMs or reservations in your project.
- The value of Matching count equals Total count. In this case, Compute Engine won't provision any reserved VMs for the future reservation request .
If you modify the future reservation request, or create new VMs or reservations with VM properties that match the request, then Compute Engine will update the value in the Matching count column within 30 minutes. To verify when the Matching count column was last updated, view the request's details, and then check the value in the Last matching usage evaluation time row.
Optional: To change the number of reserved VMs in a future reservation request, modify your future reservation request.

gcloud

View the details of the future reservation request.
In the output, subtract the value of the existingMatchingUsageInfo field from the totalCount field. If the value of existingMatchingUsageInfo.count equals totalCount, then Compute Engine won't provision any reserved VMs for the future reservation request.

If you modify the future reservation request, or create new VMs or reservations with VM properties that match the request, then Compute Engine will update the existingMatchingUsageInfo field within 30 minutes. To verify when the field was last updated, check the value of the existingMatchingUsageInfo.timestamp field.
Optional: To change the number of reserved VMs in your future reservation request, modify your future reservation request.

REST

View the details of the future reservation request.
In the output, subtract the value of the existingMatchingUsageInfo field from the totalCount field. If the value of existingMatchingUsageInfo.count equals totalCount, then Compute Engine won't provision any reserved VMs for the future reservation request.

If you modify the future reservation request, or create new VMs or reservations with VM properties that match the request, then Compute Engine will update the existingMatchingUsageInfo field within 30 minutes. To verify when the field was last updated, check the value of the existingMatchingUsageInfo.timestamp field.
Optional: To change the number of reserved VMs in your future reservation request, modify your future reservation request.

What's next

Learn how to modify future reservation requests.
Learn how to cancel or delete future reservation requests.
After you reach the start time of your reservation period, learn how to consume the auto-created reservations.
After the end time of your reservation period, learn how to do the following:
- Modify the auto-created reservations.
- Delete the auto-created reservations.