Quota project overview

This page defines the use of the quota project, and how the project is determined. Ensuring that your quota project is set correctly can help you avoid failed requests to Google Cloud APIs and unnecessary quota errors.

Every request to a Google Cloud API is counted against a quota. Because quotas are enforced on each project, that means that every request needs a project to provide quota. That project is called the quota project. It's also sometimes referred to as the billing project. The billing project and the quota project are the same project. To learn more, see How to set the quota project.

How the quota project is determined

How the quota project is determined depends on the type of API you use: resource-based API or client-based API.

Resource-based APIs

For resource-based Google Cloud APIs, the project that provides quota for an API call is also the project that contains the resource that is being accessed. For example, when you create a Compute Engine instance, you must specify the project for that new instance. The project then contains the newly created instance. Later, if you perform operations on the Compute Engine instance, the project that contains the instance provides the quota for the request. This applies regardless of whether you use the Google Cloud CLI, REST API, or client libraries.

You cannot change the quota project used by a request to a resource-based API. The request always uses the project that contains the resource that the request is operating on.

Client-based APIs

If an API is not a resource-based API, it's a client-based API. For example, the Cloud Translation API is a commonly used client-based API.

When you make a request to a client-based API, if a quota project cannot be identified, the request fails.

The quota project can be set in multiple ways, and the project will be verified by checking the following options. The order listed is the order of their precedence.

  • The quota project set in the environment or in the request.
  • If you use an API key to provide credentials for a request, the project associated with the API key is used as the quota project.
  • If you use the Google Cloud CLI to get your access token, and you've authenticated to the gcloud CLI with your user credentials, the gcloud CLI shared project is sometimes used as the quota project. Not all client-based APIs fall back on the shared project.
  • If the principal for the API call is a service account, including by impersonation, the project associated with the service account is used as the quota project.
  • If the principal for the API is a workforce identity federation user, the workforce pools user project is used as the quota project.

If none of the previous checks yield a quota project, the request fails.

About the gcloud CLI shared project for client-based APIs

If you use the gcloud CLI to make a request to a client-based API without setting the quota project, the request might fall back on the gcloud CLI shared project, or the request might fail. The gcloud CLI shared project is used by all gcloud CLI requests in all projects, so if many other gcloud CLI requests are also using this project as their quota project, the quota for the shared project might be temporarily depleted. If this happens, your request fails with an out-of-quota error message.

Identify the current quota project for client-based APIs

To identify the project used for a gcloud CLI command, include the --log-http flag with the gcloud CLI to print the headers for the command. The log includes the project used for this command as the quota project in the X-Goog-User-Project field.

Determine if an API is resource-based or client-based

It can be difficult to determine which type of API you're using. However, activation and quota are enforced in the same way. If a service account from project A calls a read method in project B, and neither project has the API enabled, the API not enabled error message indicates which project is checked for activation. The project checked for activation is the same project checked for rate quota.

What's next