Listing group filters in batch jobs

When you work with listing group filters in the context of an AdGroupCriterion.listing_group or an AssetGroupListingGroupFilter , take the following considerations into account when designing your integration.

Batch splitting

If there are any operations in a batch job that contain ad group criteria or asset group listing group filters, the operations in the batch job are split into multiple sub-batches when received by the Google Ads API server. Note that unlike standard operations in a batch job, each sub-batch containing listing group filter operations is treated atomically.

The way in which batch jobs containing listing group filters are split into sub-batches is determined by the following factors:

1. Type of listing group filter
2. The AdGroupCriterion or AssetGroup the listing group filter is targeting
3. Order of operations

Consider how operations are grouped:

• All consecutive AssetGroupListingGroupFilterOperation operations targeting the same AssetGroup are grouped together in an atomic sub-batch (no partial failure behavior).
• All consecutive AdGroupCriterionOperation operations that contain a listing_group targeting the same AdGroup are grouped together in an atomic sub-batch (no partial failure behavior).
• All other consecutive operations are grouped together in non-atomic sub-batches (partial failure behavior).

The following diagram illustrates this concept. Each of the gray boxes represents a batch job as submitted using the Google Ads API. Within the gray boxes, the individual operations are grouped by color to represent the sub-batches that the Google Ads API server creates. The order of the operations in each of the gray boxes corresponds to the order in which the operations would have been added to the batch job.

Limitations

When working with listing group filters in the context of batch jobs, the following limitations apply:

• A single batch of AssetGroupListingGroupFilterOperation operations containing a listing_group and targeting the same AdGroup cannot exceed 20,000 operations in length. However, it is recommended not to exceed 10,000 operations.
• A single batch of AssetGroupListingGroupFilterOperation operations targeting the same AssetGroup cannot exceed 10,000 operations.
• Violating either of these conditions results in the entire batch job failing.

Troubleshooting

Listing group filter operations in a batch job are processed as one transaction, which can lead to scenarios where many operations fail due to a small number of erroneous operations. Further, because of the way BatchJob operations are processed, the root cause of the failures may appear at an index before or after the downstream failures.

For example, when processing a response from ListBatchJobResults , you may find that several operations failed with a status message, Ad group is invalid due to the listing groups it contains . This message typically indicates that the operation at this index was cancelled because of a failed operation at a different index. To identify the root cause of the issue, we recommend iterating through all status messages in the BatchJobResult —before and after the index of the Ad group is invalid error message—in search of additional error information.