View and manage quotas using the gcloud alpha CLI

The following sections contain example gcloud alpha quotas info and gcloud alpha quotas preferences commands. These commands allow you to view and manage QuotaInfo and QuotaPreference resources.

You can use the Google Cloud CLI (gcloud CLI) to get current quotas values and specify quota preferences for some Google Cloud APIs and services.

Limitations

Cloud Quotas has the following limitations:

Quota increase adjustments must be made at the project-level and are subject to Google Cloud approval.
You can request quota decrease adjustments for project-, folder-, and organization-level quotas.
The Cloud Quotas API only supports project-level operations. Folder-level and organization-level operations are not supported.

Before you begin

Before you use the gcloud CLI, make sure that you install and initialize the gcloud CLI.

You may also need your QUOTA_ID value. If so, see the instructions for finding your quota ID.

Install and initialize the gcloud CLI

To use the gcloud CLI for Cloud Quotas, be sure to install and initialize components:

Install the gcloud CLI.

If you're using Cloud Shell, you can skip this step because gcloud CLI comes pre-installed.
Initialize the gcloud CLI.
Install the alpha component by running the following command:
```
gcloud components install alpha
```

Find your quota ID

Several gcloud CLI commands on this page refer to your quota ID value. You can find the quota ID using the Google Cloud console, the gcloud CLI, client libraries, or the REST API. This section shows how to find the quota ID using either the Google Cloud console or gcloud CLI.

Console

Go to the Quotas & System Limits page:
Go to Quotas & System Limits
Click Filter to filter for your service.
If you don't see the Limit name column, click the icon Column display options.... Select Limit name and click OK.
The Limit name column shows the quota ID.

gcloud

To find the quota ID value by using the gcloud CLI, run the following command to list your quota information for the specified service:

Enter the following gcloud CLI command in a terminal window:
```
gcloud alpha quotas info list --service=SERVICE_NAME --project=PROJECT_ID_OR_NUMBER \
--billing-project=BILLING_PROJECT_ID_OR_NUMBER
```
Replace the following:
- SERVICE_NAME: the service name with quotas that you want to see—for example, the service name for Compute Engine is compute.googleapis.com
- PROJECT_ID_OR_NUMBER: the project ID or project number
  
  To find your project ID using the Google Cloud console, navigate to the Resource Manager page:
  Go to Resource Manager
- BILLING_PROJECT_ID_OR_NUMBER: the project ID or project number for quota and billing use. Running a gcloud command affects quota as if you made the equivalent request directly through a REST or RPC API.
  
  Specify the project whose quota you want to use. This can be different from the project containing the service that you're finding the quota ID for.
  
  If you already set the billing project when setting up the gcloud CLI, this flag is optional. Otherwise, omitting it might cause a permission denied error. For more information, see Set the quota project.

The output from the gcloud alpha quotas info list command contains text similar to the following sample:

...
"quotaInfos": [
    ...
    {
        "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/CPUS-per-project-region",
        "quotaId": "CPUS-per-project-region",
        "metric": "compute.googleapis.com/cpus",
        "containerType": "PROJECT",
        "dimensions": [
            "region"
        ],
        "dimensionsInfo": [
            {
                "details": {
                    "value": 20
                },
                "applicableLocations": [
                    "us-central1",
                    "us-central2",
                    "us-west1",
                    "us-east1"
                ]
                ...
            }
        ]
    },
    ...
]
...

Look for the value that corresponds to quotaId and use it when specifying QUOTA_ID in the following sections.

Example gcloud quota information commands

This section provides examples that show how to use gcloud alpha quotas info commands to view quota information for a particular service or for an organization.

QuotaInfo is a read-only resource that provides metadata and quota value information about a particular quota for a given project, folder or organization.

View quota information for a particular service

To view quota information for a particular service, run the following command:

gcloud alpha quotas info describe QUOTA_ID --service=SERVICE_NAME \
    --project=PROJECT_ID_OR_NUMBER --billing-project=BILLING_PROJECT_ID_OR_NUMBER

Replace the following:

QUOTA_ID: the quota ID value. To find this value, see Find your quota ID.
SERVICE_NAME: the service name with quotas that you want to see—for example, the service name for Compute Engine is compute.googleapis.com
PROJECT_ID_OR_NUMBER: the project ID or project number
BILLING_PROJECT_ID_OR_NUMBER: the project ID or project number for quota and billing use. Running a gcloud command affects quota as if you made the equivalent request directly through a REST or RPC API.

Specify the project whose quota you want to use. This can be different from the project containing the service that you're viewing quota info for.

If you already set the billing project when setting up the gcloud CLI, this flag is optional. Otherwise, omitting it might cause a permission denied error. For more information, see Set the quota project.

View quota information for an organization

To view the same service's quota details for an organization, run the following command:

gcloud alpha quotas info list --service=SERVICE_NAME --organization=ORGANIZATION_ID \
    --billing-project=BILLING_PROJECT_ID_OR_NUMBER

Replace the following:

SERVICE_NAME: the service name with quotas that you want to see—for example, the service name for Compute Engine is compute.googleapis.com
ORGANIZATION_ID: the ID of your organization
BILLING_PROJECT_ID_OR_NUMBER: the project ID or project number for quota and billing use. Running a gcloud command affects quota as if you made the equivalent request directly through a REST or RPC API.

Specify the project whose quota you want to use. This can be different from the project containing the service that you're viewing quota info for.

If you already set the billing project when setting up the gcloud CLI, this flag is optional. Otherwise, omitting it might cause a permission denied error. For more information, see Set the quota project.

Example gcloud quota preferences commands

This section provides examples that show how to use gcloud alpha quotas preferences commands to check existing quota preferences and adjust the quota value.

The QuotaPreference resource represents your preference for a particular dimension combination. A dimension is an attribute that represents a region or a zone, or a service-specific dimension, such as gpu_family or network_id.

Check for existing preferences

To check for existing preferences, run the following command:

gcloud alpha quotas preferences list --project=PROJECT_ID_OR_NUMBER \
    --billing-project=BILLING_PROJECT_ID_OR_NUMBER

Replace the following:

PROJECT_ID_OR_NUMBER : the project ID or project number
BILLING_PROJECT_ID_OR_NUMBER: the project ID or project number for quota and billing use. Running a gcloud command affects quota as if you made the equivalent request directly through a REST or RPC API.

Specify the project whose quota you want to use. This can be different from the project that you're checking quota preferences for.

If you already set the billing project when setting up the gcloud CLI, this flag is optional. Otherwise, omitting it might cause a permission denied error. For more information, see Set the quota project.

Check for existing preferences with pending quota adjustments

To check for existing preferences with pending quota adjustments, add the --reconciling-only=true flag as shown in the following command:

gcloud alpha quotas preferences list --project=PROJECT_ID_OR_NUMBER --reconciling-only=true \
    --billing-project=BILLING_PROJECT_ID_OR_NUMBER

Replace the following:

PROJECT_ID_OR_NUMBER : the project ID or project number
BILLING_PROJECT_ID_OR_NUMBER: the project ID or project number for quota and billing use. Running a gcloud command affects quota as if you made the equivalent request directly through a REST or RPC API.

Specify the project whose quota you want to use. This can be different from the project that you're checking quota preferences for.

If you already set the billing project when setting up the gcloud CLI, this flag is optional. Otherwise, omitting it might cause a permission denied error. For more information, see Set the quota project.

Request a quota increase adjustment when a quota preference hasn't been set yet

To request a quota increase adjustment for a specific region when a preference hasn't yet been set, run the following command:

gcloud alpha quotas preferences create --preferred-value=PREFERRED_VALUE \
    --quota-id=QUOTA_ID --service=SERVICE_NAME  --project=PROJECT_ID_OR_NUMBER \
    --billing-project=BILLING_PROJECT_ID_OR_NUMBER --email=EMAIL --preference-id=PREFERENCE_ID

Replace the following:

PREFERRED_VALUE: the preferred quota value
QUOTA_ID: the quota ID value. To find this value, see Find your quota ID.
SERVICE_NAME: the service name with quotas that you want to see—for example, the service name for Compute Engine is compute.googleapis.com
PROJECT_ID_OR_NUMBER: the project ID or project number
BILLING_PROJECT_ID_OR_NUMBER: the project ID or project number for quota and billing use. Running a gcloud command affects quota as if you made the equivalent request directly through a REST or RPC API.

Specify the project whose quota you want to use. This can be different from the project that you're requesting a quota adjustment for.

If you already set the billing project when setting up the gcloud CLI, this flag is optional. Otherwise, omitting it might cause a permission denied error. For more information, see Set the quota project.
EMAIL: an email address that can be used as a contact, in case Google Cloud needs more information to make a decision before additional quota can be granted
PREFERENCE_ID: an optional preference ID; if you don't specify a preference ID, the API generates a Universally Unique Identifier (UUID) for you

Request a quota increase adjustment when a quota preference has been set

To request a quota increase adjustment for a specific region and there is already a preference, run the following command:

gcloud alpha quotas preferences update PREFERENCE_ID --preferred-value=PREFERRED_VALUE \
    --quota-id=QUOTA_ID --service=SERVICE_NAME --project=PROJECT_ID_OR_NUMBER \
    --email=EMAIL --billing-project=BILLING_PROJECT_ID_OR_NUMBER

Replace the following:

PREFERENCE_ID: the preference ID, which is required as the first argument when using the gcloud alpha quotas preferences update command
PREFERRED_VALUE: the preferred quota value
QUOTA_ID: the quota ID value. To find this value, see Find your quota ID.
SERVICE_NAME: the service name with quotas that you want to see—for example, the service name for Compute Engine is compute.googleapis.com
PROJECT_ID_OR_NUMBER: the project ID or project number
EMAIL: an email address that can be used as a contact, in case Google Cloud needs more information to make a decision before additional quota can be granted
BILLING_PROJECT_ID_OR_NUMBER: the project ID or project number for quota and billing use. Running a gcloud command affects quota as if you made the equivalent request directly through a REST or RPC API.

Specify the project whose quota you want to use. This can be different from the project that you're requesting a quota adjustment for.

If you already set the billing project when setting up the gcloud CLI, this flag is optional. Otherwise, omitting it might cause a permission denied error. For more information, see Set the quota project.

Request a quota increase adjustment using a dimension

To request a quota increase adjustment using a dimension, run the following command:

gcloud alpha quotas preferences create --preferred-value=PREFERRED_VALUE \
    --quota-id=QUOTA_ID --service=SERVICE_NAME --project=PROJECT_ID_OR_NUMBER \
    --dimensions=KEY1=VALUE1,KEY2=VALUE2,... --billing-project=BILLING_PROJECT_ID_OR_NUMBER \
    --email=EMAIL --justification=JUSTIFICATION --preference-id=PREFERENCE_ID

Replace the following:

PREFERRED_VALUE: the preferred quota value
QUOTA_ID: the quota ID value. To find this value, see Find your quota ID.
SERVICE_NAME: the service name with quotas that you want to see—for example, the service name for Compute Engine is compute.googleapis.com
PROJECT_ID_OR_NUMBER: the project ID or project number
KEY1=VALUE1,KEY2=VALUE2,...: an optional list that specifies your dimension as a comma-separated list of key-value pairs. For example, your dimension might specify the following Compute Engine values:
- KEY1=VALUE1: region=us-east4
- KEY2=VALUE2: gpu_family=NVIDIA_H100
BILLING_PROJECT_ID_OR_NUMBER: the project ID or project number for quota and billing use. Running a gcloud command affects quota as if you made the equivalent request directly through a REST or RPC API.

Specify the project whose quota you want to use. This can be different from the project that you're requesting a quota adjustment for.

If you already set the billing project when setting up the gcloud CLI, this flag is optional. Otherwise, omitting it might cause a permission denied error. For more information, see Set the quota project.
EMAIL: an email address that can be used as a contact, in case Google Cloud needs more information to make a decision before additional quota can be granted
JUSTIFICATION: an optional string that explains your request
PREFERENCE_ID: an optional preference ID; if you don't specify a preference ID, the API generates a Universally Unique Identifier (UUID) for you

The output would contain data specific to your configuration and look similar to the following example output:

{
    "createTime":"CREATE_TIME",
    "dimensions":{
        "gpu_family":"NVIDIA_H100",
        "region":"us-east4"
    },
    "etag":"ETAG_VALUE",
    "name":"projects/12345/locations/global/quotaPreferences/PREFERENCE_ID",
    "quotaConfig":{
        "grantedValue":"0",
        "preferredValue":"128",
        "traceId":"TRACE_ID"
    },
    "quotaId":"GPUS-PER-GPU-FAMILY-per-project-region",
    "reconciling":true,
    "service":"compute.googleapis.com",
    "updateTime":"UPDATE_TIME",
}

View an existing quota preference

To view the details of the quota preference that you just created, run the following command:

gcloud alpha quotas preferences describe PREFERENCE_ID \
    --project=PROJECT_ID_OR_NUMBER \
    --billing-project=BILLING_PROJECT_ID_OR_NUMBER

Replace the following:

PREFERENCE_ID: the preference ID, which is required as the first argument when using the gcloud alpha quotas preferences describe command
PROJECT_ID_OR_NUMBER: the project ID or project number
BILLING_PROJECT_ID_OR_NUMBER: the project ID or project number for quota and billing use. Running a gcloud command affects quota as if you made the equivalent request directly through a REST or RPC API.

Specify the project whose quota you want to use. This can be different from the project that you're viewing the quota preference for.

If you already set the billing project when setting up the gcloud CLI, this flag is optional. Otherwise, omitting it might cause a permission denied error. For more information, see Set the quota project.

The output would contain data specific to your configuration and look similar to the following example output:

createTime: 'CREATE_TIME'
dimensions:
  gpu_family: NVIDIA_H100
  region: us-east4
etag: ETAG_VALUE
name: projects/12345/locations/global/quotaPreferences/PREFERENCE_ID
quotaConfig:
  grantedValue: '0'
  preferredValue: '128'
  traceId: TRACE_ID
quotaId: GPUS-PER-GPU-FAMILY-per-project-region
reconciling: true
service: compute.googleapis.com
updateTime: 'UPDATE_TIME'

Other services with quota-related gcloud CLI commands

In addition to gcloud alpha quotas, some services have their own command-line access to quota and resource usage information.

For example, Compute Engine lets you access quota information. For details, see the following Compute Engine sections:

Allocation quotas
The gcloud CLI compute overview
The gcloud CLI compute section of the Google Cloud SDK reference.

What's next

To troubleshoot issues with gcloud alpha quotas commands, see Troubleshooting gcloud CLI errors.
For details about gcloud alpha quotas commands and flags, see the gcloud alpha quotas section of the Google Cloud CLI reference.
For more information about quotas terminology, see Understand quota values and system limits.