Google Ads API Resource Usage Policy Update

What's changing?

We are updating the Google Ads API resource usage policy to throttle GoogleAdsService.Search and GoogleAdsService.SearchStream query patterns that consume excessive amounts of API resources. If a particular query pattern is throttled, other services, methods, and query patterns will continue to work unaffected.

Starting the week of June 17, 2024, and only for the throttled query patterns, requests will be affected as follows:

• If you use version v17 or older of the API, you will receive a QuotaError.RESOURCE_EXHAUSTED error.
• If you use version v18 or later of the API, you will receive a QuotaError.EXCESSIVE_SHORT_TERM_QUERY_RESOURCE_CONSUMPTION or QuotaError.EXCESSIVE_LONG_TERM_QUERY_RESOURCE_CONSUMPTION, depending on whether the excessive resource consumption was for a short period of time (a few minutes), or a long period of time.

To help you identify and monitor your expensive reports, we will also return a cost metric for individual reports. To view the cost for successful reports, see the following fields:

• SearchGoogleAdsResponse.query_resource_consumption field when running reports using GoogleAdsService.Search method.
• SearchGoogleAdsStreamResponse.query_resource_consumption field when running reports using the GoogleAdsService.SearchStream method.

Why this change?

We are making this change to preserve the reliability and stability of the API.

What do I need to do?

Before June 17, 2024, update your applications to do the following:

• Handle the new error codes when making GoogleAdsService::Search or GoogleAdsService::SearchStream calls
  • If you use version v17 or earlier of the Google Ads API, then handle QuotaError.RESOURCE_EXHAUSTED errors.
  • If you use version v18 or later of the API, handle the QuotaError.EXCESSIVE_SHORT_TERM_QUERY_RESOURCE_CONSUMPTION and QuotaError.EXCESSIVE_LONG_TERM_QUERY_RESOURCE_CONSUMPTION errors.
  • If one or more of your reporting query patterns are throttled, you should review and fix the query pattern. Here are some ways to improve query performance:
  • Run the query less frequently.
  • Use a less expensive query pattern or view.

To learn more about optimizing your queries, see manage data efficiency.

• [Optional] Incorporate the new query_resource_consumption metric into your monitoring systems to detect and handle new expensive queries.

How to get help

If you have any questions about this change or need help optimizing specific query patterns, check out the Google Ads API support page for options.

- David Stevens, Google Ads API Product Manager