Managing Service Quota

This page describes how to view all quota metrics and limits on a Google Cloud project for a specific service, and how to cap the quota usage for that service using a quota override. You can use Service Usage to manage quota for your projects for any service, including public Google Cloud services and private services created using Cloud Endpoints. For more information on the differences between public and private APIs and services, see Public and Private Services.

Be sure to familiarize yourself with the service quota model to better understand the terminology used in this tutorial.

For most operational use cases, the simplest way to manage quota is to use Google Cloud Console. If you need to program against the Service Usage API, we recommend that you use one of our provided client libraries. To experiment with the API, you can follow the instructions in this guide and use the curl command to test the API without setting up a full application development environment.

Before you begin

To manage service quotas you need:

Displaying service quota

For the purpose of this tutorial we'll use a project named my-project-id and a service named service.googleapis.com. In each gcurl command, substitute your own project and service of interest.

To see all quota metrics and limits that apply to a specific consumer on a service, use the following command:

gcurl https://serviceusage.googleapis.com/v1beta1/projects/project-id/services/service.googleapis.com/quotaMetrics

The call responds with a list of metrics defined by the service, each with the list of limits on those metrics that apply to this consumer, the values for those limits, and any overrides. Here's an example response:

{
  "metrics": [
    {
      "name": "projects/my-project-id/services/serviceusage.googleapis.com/quotaMetrics/serviceusage.googleapis.com%2Fdefault_requests",
      "metricName": "serviceusage.googleapis.com/default_requests"
      "displayName": "Default requests",
      "consumerQuotaLimits": [
        {
          "name": "projects/my-project-id/services/serviceusage.googleapis.com/quotaMetrics/serviceusage.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject",
          "metric": "serviceusage.googleapis.com/default_requests"
          "unit": "1/min/{project}",
          "quotaBuckets": [
            {
              "effectiveLimit": "120",
              "defaultLimit": "120",
            }
          ]
        }
      ],
    },
    {
      "name": "projects/my-project-id/services/serviceusage.googleapis.com/quotaMetrics/serviceusage.googleapis.com%2Fmutate_requests",
      "metricName": "serviceusage.googleapis.com/mutate_requests"
      "displayName": "Mutate requests",
      "consumerQuotaLimits": [
        {
          "name": "projects/my-project-id/services/serviceusage.googleapis.com/quotaMetrics/serviceusage.googleapis.com%2Fmutate_requests/limits/%2Fmin%2Fproject",
          "metric": "serviceusage.googleapis.com/mutate_requests"
          "unit": "1/min/{project}",
          "quotaBuckets": [
            {
              "effectiveLimit": "30",
              "defaultLimit": "30",
            }
          ]
        }
      ],
    }
  ]
}

Each metric in the response has a name field; to inspect quota settings for just that metric, rather than for all metrics, use its name in the URL:

gcurl https://serviceusage.googleapis.com/v1beta1/projects/my-project-id/services/serviceusage.googleapis.com/quotaMetrics/serviceusage.googleapis.com%2Fdefault_requests

Similarly, each limit within a metric has a name field; to inspect quota settings for just that limit on that metric, rather than for all limits on a metric or all metrics, use its name in the URL:

gcurl https://serviceusage.googleapis.com/v1beta1/projects/my-project-id/services/serviceusage.googleapis.com/quotaMetrics/serviceusage.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject

Creating a consumer quota override

The owner of a project may apply a consumer override to a specific quota limit on that project, to reduce the total amount of quota that the consumer can charge against that limit.

Note that a consumer override cannot increase the available quota beyond what is allowed by the service default and any existing overrides by other parties (such as the service owner or an organization's quota administrator). To increase available quota, use the Edit Quotas option on the main quota page, or ask the org admin for a quota uplift.

To identify a limit to override, first use one of the methods above to find the quota limit of interest, and then use its name field to create a new consumer override in the collection of overrides for that limit:

gcurl https://serviceusage.googleapis.com/v1beta1/{name}/consumerOverrides -d '{"override": {"override_value": "135"} }'

This call can be used to apply a new override or to update an existing override to a new value.

If the call succeeds, it will return an operation identifier, which represents ongoing work on the server, as the quota change propagates to backend systems:

{
  "name": "operations/quf.92accba3-6530-4fc1-9a95-c1280d48a6b7"
}

To check the progress of the operation, just use its name:

gcurl https://serviceusage.googleapis.com/v1/{name}

When this call responds with a message that includes done: true, then the operation is finished. If the operation failed, the message will include error details. You can also check whether a change has been applied by repeating the original get call on the specific limit. The limit should now have an additional "consumerOverride" field.

Forcing large quota changes

If an override would cause the enforced quota to decrease by more than 10%, the call is rejected, as a safety measure to avoid accidentally decreasing quota too quickly. To disregard this restriction, use the force flag:

gcurl https://serviceusage.googleapis.com/v1beta1/{name}/consumerOverrides -d '{ {"override" : {"override_value": "0"}, "force": true}'

Applying regional or zonal quota overrides

Some quota limits are enforced on a per-region or per-zone basis; this is indicated by the presence of /{region} or /{zone} in the unit field of the limit. Applying an override to such a limit changes the base quota on each region or zone. To change the quota for only a specific region or zone, add a quota dimension to the override:

gcurl https://serviceusage.googleapis.com/v1beta1/{name}/consumerOverrides -d '{"override": {"override_value": "135", "dimensions": {"region": "asia-south1"} } }'