Best practices and limitations

Page Summary

• Optimize throughput by using fewer larger jobs and ordering operations by type and parent resource.

• Avoid concurrency issues by minimizing operations on the same objects across concurrent jobs and within a single job.

• Retrieve results efficiently by avoiding frequent polling and limiting results per page to 1,000.

• Batch jobs support up to one million operations, with a limit of 100 active or pending jobs per account, and requests for adding operations have size and operation count limits.

Consider these guidelines when using BatchJobService.

Improve throughput

• Fewer larger jobs are preferred over many smaller jobs.

• Order uploaded operations by operation type (except for interdependent operations that must be grouped consecutively in atomic sub-batches). For example, if your job contains operations to add standard campaigns, ad groups, and ad group criteria, order the operations in your upload so that all of the campaign operations are first, followed by all of the ad group operations, and finally all ad group criterion operations.

• Within operations of the same type, it can improve performance to group them by parent resource. For example, if you have a series of AdGroupCriterionOperation objects, it is more efficient to group operations by ad group rather than intermixing operations that affect ad group criteria in different ad groups.

Atomicity in batch splitting

The Google Ads API splits the operations in a submitted batch job into smaller sub-batches for processing. While standard sub-batches execute with partial failure enabled, sub-batches for certain interdependent operations are processed atomically as a single transaction:

• Consecutive AdGroupCriterionOperation operations (create, update, and remove) for LISTING_GROUP criteria (AdGroupCriterion.listing_group) targeting the same AdGroup (fails with CriterionError.LISTING_GROUP_ERROR_IN_ANOTHER_OPERATION if any operation in the group fails).
• Consecutive AssetGroupListingGroupFilterOperation operations (create, update, and remove) targeting the same AssetGroup (fails with BatchJobError.ASSET_GROUP_LISTING_GROUP_FILTER_TRANSACTION_FAILURE if any operation in the group fails).
• An AssetGroupOperation (create) immediately followed by up to 999 AssetGroupAssetOperation (create) operations targeting the same AssetGroup (fails with BatchJobError.ASSET_GROUP_AND_ASSET_GROUP_ASSET_TRANSACTION_FAILURE if any operation in the group fails). Each AssetGroupOperation (update or remove) executes in its own standalone single-operation sub-batch.
• A Performance Max CampaignOperation (create) with Brand Guidelines enabled (brand_guidelines_enabled set to true or left unset, since it defaults to true unless explicitly set to false or creating a Performance Max for travel goals campaign) immediately followed by up to 999 CampaignAssetOperation (create) operations targeting the same Campaign (fails with BatchJobError.CAMPAIGN_AND_CAMPAIGN_ASSET_TRANSACTION_FAILURE if any operation in the group fails). Retail Performance Max campaigns (with a Merchant Center feed) can be created without linking brand CampaignAsset resources in the same atomic sub-batch.

For both AssetGroup and Performance Max Campaign creation sub-batches (up to 1,000 operations total per sub-batch; any child create operations beyond 999 spill into the next non-atomic sub-batch):

• The parent create operation (resource_name on AssetGroup or Campaign) and its consecutive child create operations (asset_group on AssetGroupAsset or campaign on CampaignAsset) must specify the same negative temporary ID.
• Place any prerequisite AssetOperation (create) operations for new Asset resources before the parent AssetGroupOperation or CampaignOperation (create), never between the parent create and its child link create operations (which would immediately close the atomic sub-batch and split the parent resource creation from its linked assets).

When an atomic sub-batch fails, the offending operation's BatchJobResult.status contains the underlying validation error, while the remaining operations in that sub-batch are rolled back with the corresponding transaction error for that sub-batch. Inspect the adjacent BatchJobResult entries sharing the same AdGroup, AssetGroup, or Campaign ID to identify the root-cause error.

If related operations in any of these groups are not added consecutively, the Google Ads API splits them across separate sub-batches, causing the modification to fail minimum asset requirements or leaving listing group trees incomplete. See Use listing group filters in batch jobs and Performance Max batch processing for details.

Logical grouping

When modifying a product targeting hierarchy (AssetGroupListingGroupFilterOperation in Performance Max campaigns or AdGroupCriterionOperation in Shopping campaigns) or creating a new AssetGroup or Performance Max Campaign, group all operations targeting the same parent resource (AssetGroup, AdGroup, or Campaign) consecutively. This reduces backend lock contention and keeps interdependent trees together.

Data consistency

Because listing group filter trees and Performance Max asset requirements are validated at the end of each atomic sub-batch transaction, avoid splitting updates to the same parent resource across discontinuous ranges in a job or across concurrent jobs.

Avoid concurrency issues

• When submitting multiple concurrent jobs for the same account, reduce the likelihood of jobs operating on the same objects at the same time while maintaining large job sizes. Many unfinished jobs with the status of RUNNING that try to mutate the same set of objects can lead to deadlock-like conditions, resulting in severe slow-down and even job failures.

• Don't submit multiple operations that mutate the same object in the same job, as the result can be unpredictable.

Retrieve results optimally

• Don't poll the job status too frequently or you risk hitting rate limit errors.

• Leave page_size unset (or set it to the maximum of 1000) when calling ListBatchJobResults to minimize pagination round trips, and only set response_content_type to MUTABLE_RESOURCE if your application inspects the returned resource fields beyond resource_name.

• The results order is the same as the upload order.

Additional usage guidance

• You can set an upper bound for how long a batch job is allowed to run before being canceled. When creating a new batch job, set the metadata.execution_limit_seconds field to your preferred time limit, in seconds. There is no default time limit if metadata.execution_limit_seconds is not set.

• Although the protocol limit is 10,000 operations per request, we recommend adding no more than 1,000 operations per AddBatchJobOperationsRequest and using the sequence_token to upload the rest of the operations to the same job. Depending on the size of the operations, sending too many operations in a single AddBatchJobOperationsRequest can cause a BatchJobError.REQUEST_TOO_LARGE error. You can handle this error by reducing the number of operations and retrying the AddBatchJobOperationsRequest.

Limitations

• Each BatchJob supports up to one million operations. Exceeding this limit when calling AddBatchJobOperations returns a ResourceCountLimitExceededError.RESOURCE_LIMIT error (with ResourceLimitType.BATCH_JOB_OPERATIONS_PER_JOB in ErrorDetails.resource_count_details).

• Each account can have up to 100 active or pending jobs at the same time. Exceeding this limit when creating a batch job with MutateBatchJob returns a ResourceCountLimitExceededError.RESOURCE_LIMIT error (with ResourceLimitType.BATCH_JOBS_PER_CUSTOMER in ErrorDetails.resource_count_details).

• Pending jobs older than 7 days are automatically removed.

• Each AddBatchJobOperationsRequest has a hard limit of 10,000 mutate operations per request. Exceeding 10,000 operations in a single request returns a BatchJobError.REQUEST_TOO_LARGE error.

• For the page_size field in ListBatchJobResultsRequest:

  • If page_size is not set or is 0, it defaults to the maximum of 1000.
  • If page_size exceeds 1000, or is less than 0, the API returns a BatchJobError.INVALID_PAGE_SIZE error.

• Each AddBatchJobOperationsRequest has a maximum size of 41,937,920 bytes. If you exceed this limit, you receive a BatchJobError.REQUEST_TOO_LARGE error (or an INTERNAL_ERROR if rejected at the transport layer). You can determine the serialized size of the request before submitting and take appropriate action if it is too large:

  Java

  
  static final int MAX_REQUEST_BYTES = 41_937_920;
  
  // ... (code to get the AddBatchJobOperationsRequest object)
  
  int sizeInBytes = request.getSerializedSize();
  

  C#

  
  const int MAX_REQUEST_BYTES = 41_937_920;
  
  // ... (code to get the AddBatchJobOperationsRequest object)
  
  int sizeInBytes = request.CalculateSize();
  

  PHP

  
  const MAX_REQUEST_BYTES = 41937920;
  
  // ... (code to get the AddBatchJobOperationsRequest object)
  
  $size_in_bytes = $request->byteSize();
  

  Python

  
  MAX_REQUEST_BYTES = 41_937_920
  
  # ... (code to get the AddBatchJobOperationsRequest object)
  
  size_in_bytes = type(request).pb(request).ByteSize()
  

  Ruby

  
  MAX_REQUEST_BYTES = 41_937_920
  
  # ... (code to get the AddBatchJobOperationsRequest object)
  
  size_in_bytes = request.to_proto.bytesize
  

  Perl

  
  use JSON::XS;
  use constant MAX_REQUEST_BYTES => 41937920;
  
  # ... (code to get the AddBatchJobOperationsRequest object)
  
  # The Perl client library uses REST/JSON; UTF-8 JSON byte length provides a
  # conservative upper-bound estimate of the serialized request size.
  my $json_encoder = JSON::XS->new->utf8->convert_blessed;
  my $size_in_bytes = length($json_encoder->encode($request));
  

Single mutate operation size

While the overall request can be up to 41,937,920 bytes, the serialized size of a single MutateOperation within the batch is capped at 10,484,504 bytes (10 MiB minus 1,256 bytes). Exceeding this limit returns a BatchJobError.REQUEST_TOO_LARGE error. Note that while the reference documentation for BatchJobError.REQUEST_TOO_LARGE cites the 10,484,504-byte threshold, AddBatchJobOperations returns this same error code when any of the three request thresholds (41,937,920 total request bytes, 10,484,504 single-operation bytes, or 10,000 operations per call) is exceeded, with the error's message field specifying which limit was violated.