API limits and quotas

  • The Google Ads API enforces various limits on operations and request types, including daily API operations, mutate requests, and service-specific requests.

  • Daily API usage is based on the number of get requests and mutate operations per developer token, with limits varying by access level.

  • gRPC message size for responses is limited to 64 MB; exceeding this may require reducing selected fields, using streaming, or sending fewer operations in mutate requests.

  • Mutate requests are limited to 10,000 operations per request, in addition to counting against the daily operation quota.

  • Specific services like Planning, Conversion Upload, Billing, Account Budget, Keyword Planning, Audience Insights, Conversion Adjustment Upload, Customer User Access, and User Data have their own particular limits and considerations.

The Google Ads API enforces limits on API operations, such as the number of operations that can be sent in a single mutate request. The following table summarizes some of the important limits and quotas to be aware of.

Request type, limitation, and error code
Operations with Test access level 15,000 API operations per day against test accounts RESOURCE_EXHAUSTED
Operations with Explorer access level 2,880 API operations per day against production accounts
15,000 API operations per day against test accounts 		RESOURCE_EXHAUSTED
Operations with Basic access level 15,000 API operations per day against both test and production accounts RESOURCE_EXHAUSTED
Operations with Standard access level Unlimited API operations per day against both test and production accounts N/A
Mutate requests 10,000 mutate operations per request TOO_MANY_MUTATE_OPERATIONS
Planning Service requests 1 QPS RESOURCE_EXHAUSTED
Conversion Upload Service requests 2,000 conversions per request TOO_MANY_CONVERSIONS_IN_REQUEST
Billing and Account Budget Service requests 1 operation per mutate request TOO_MANY_MUTATE_OPERATIONS

Daily API operation limits

Daily API usage limits are based on the number of API operations made by your Google Cloud project. API operations are the total sum of Search and SearchStream requests, individual mutate operations, and other service requests. The limits for daily API operations depend on the API access level of your Google Cloud project. The Access levels and permissible use guide outlines the specific API operation limits for each access level.

Requests that violate these limits are rejected with the error: RESOURCE_EXHAUSTED.

gRPC limitations

All of the Google Ads API client libraries use gRPC for generating requests and responses. By default, gRPC has a message size of 4 MB, but our client libraries set the max message size to 64 MB in order to increase efficiency.

Responses must not exceed this limit. For example, a search request that includes a lot of fields may generate a response that exceeds 64 MB in size. To avoid this limit, you can reduce the number of selected fields, or use streaming. For mutates, send fewer operations per request.

Requests that violate this limitation will not generate a GoogleAdsError, but will generate a RESOURCE_EXHAUSTED (gRPC code 8 / HTTP 429) error. Refer to the list of gRPC error codes and messages.

Mutate requests

In addition to counting against the user's daily operation quota, a mutate request cannot contain more than 10,000 mutate operations per request. Requests that violate this limitation are rejected with the error: TOO_MANY_MUTATE_OPERATIONS.

Additional limits and considerations for specific services and request types are outlined next.

Search requests

A Search or SearchStream request counts as one operation against the user's daily operation quota. One SearchStream request counts as one API operation irrespective of the number of batches.

Paginated requests

Paginated requests (for example, requests that contain a valid next_page_token) are not counted against a user's daily operation quota. However, pagination requests that contain an expired or invalid page token will generate an exception and will count against the daily operation quota.

For more details on pagination, refer to Paging through results.

Other types of requests

A request that is not a Mutate, Search, or SearchStream request counts as one operation against the user's daily operation quota.

A few examples of such requests include:

Requests that return API exceptions

Requests that are rejected with a GoogleAdsFailure still count against the user's daily operation quota.

Requests that fail but don't return a GoogleAdsFailure, such as from an error at the network level, won't count against the user's daily operation quota since the requests would never reach the service. An example of this is a network connectivity failure.

Keyword planning service

Due to cost and complexity, the following Keyword Planning service methods are subject to separate limits from other types of requests.

Keep in mind these limits when creating a keyword plan.

Keyword plan object Maximum number
KeywordPlan per account 10,000
KeywordPlanAdGroup per KeywordPlan 200
KeywordPlanAdGroupKeyword per KeywordPlan 10,000
KeywordPlanCampaignKeyword (negative keywords) per KeywordPlan 1,000
KeywordPlanCampaign per KeywordPlan 1

Audience insights service

The following methods within AudienceInsightsService are subject to specific quota limits.

Conversion upload service

Conversion adjustment upload service

Conversion value rules

If a ConversionValueRuleSet with an attachment_type of CUSTOMER already exists for the account, you must add any new conversion value rules to that set for them to become active. If no such conversion value rule set exists, you must create one and add your conversion value rules to it as described in Create rule sets.

Billing and account budget services

  • Mutates can only be made against accounts configured for monthly invoicing.

    Requests that violate this limitation are rejected with the error: MUTATE_NOT_ALLOWED.

  • Only 1 operation is permitted for mutate requests.

    Requests that violate this limitation are rejected with the error: TOO_MANY_MUTATE_OPERATIONS.

  • You should wait at least 12 hours between account budget (AccountBudget or AccountBudgetProposal) changes to the same account. Making changes before 12 hours have elapsed may result in unrecoverable failures which can only be resolved by your Google Ads account representative.

Invitations to customer accounts

New users can be invited to existing client accounts with the CustomerUserAccessInvitationService. Because this feature sends invitation emails to other users, it has the potential to be misused, and thus there are limitations to its behavior:

  • Users cannot receive more than one pending invitation for the same client account. If a subsequent request is made to send an invitation to a user that already has a pending invitation, this error is returned: EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION.

  • Client accounts cannot have more than 70 invitations pending at one time. If a request is sent that causes this value to be exceeded, this error is returned: PENDING_INVITATIONS_LIMIT_EXCEEDED.

User data

User data is managed with the UserDataService and the OfflineUserDataJobService.

Each UserData object in a create or remove operation pertains to a single end-user. The user_identifiers field within a single UserData object is limited to a maximum of 20 identifiers. Exceeding this limit in a single UserData object will result in an OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS or UserDataError.TOO_MANY_USER_IDENTIFIERS error.

Handle users with more than 20 identifiers

If a single end-user possesses more than 20 identifiers that you need to upload, you should distribute these identifiers across multiple UserData objects. To make sure Google can associate all these identifiers with the same end-user, each UserData object for that user must include at least one common user_identifier, such as the same hashed_email, hashed_phone_number, or third_party_user_id. Google uses these shared identifiers to link and merge the information from the separate UserData operations to the correct end-user profile.

If you rely on PII such as hashed emails or phone numbers, ensure they are normalized and hashed according to the Google Ads API requirements (SHA-256, lowercase, no whitespace) to prevent linkage failures.

For example, if a user has 30 email addresses, you can send two UserData objects that share a common third_party_user_id (putting thirdPartyUserId plus emails 1 through 19 in the first object to stay within the 20-identifier limit, and thirdPartyUserId plus emails 20 through 30 in the second):

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_1" },
    // Hashed emails 2 through 18 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_19" }
  ]
}

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_20" },
    // Hashed emails 21 through 29 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_30" }
  ]
}

The total limit for user_identifiers across all operations in a single AddOfflineUserDataJobOperationsRequest is 100,000 (an OfflineUserDataJob can accept multiple AddOfflineUserDataJobOperationsRequest calls, up to a recommended maximum of 1,000,000 operations per job). For synchronous uploads using UploadUserDataRequest (UserDataService.UploadUserData), each request is limited to a maximum of 10 operations and 100 user_identifiers across the entire request.

Other types of limits

A repeated field, such as a list of operations, that has too many items in a request can incur the error: REQUEST_SIZE_LIMIT_EXCEEDED. This same error message can also be due to other issues.

If you encounter this limitation and are making requests that use a repeated field, try reducing the number of items in the repeated field by splitting the list of operations across multiple mutate requests.

When making a GAQL query, the maximum number of items within an IN clause is 20,000. If you exceed that limit, a FILTER_HAS_TOO_MANY_VALUES error is returned.

Previous
Overview
Next
System limits