Audit Account Limits

There are limits as to the number of entities that can be active under certain Display & Video 360 resources. These account limits are relatively generous and rarely reached, but you can proactively avoid reaching them by taking the steps outlined in this guide.

Note: A request that causes you to exceed an entity limit will throw an error.

This page discusses how to get and optimize entity counts using the Display & Video 360 API.

Audit an advertiser

The total count of used entities contributing to account limits for a resource can be retrieved through advertisers.audit. These entity counts include types not retrievable or editable through the API, such as Gmail Line Items.

Here's an example of how to audit and display your current counts for a given advertiser:

Java

// Create read mask to restrict audit results to
// the relevant account limits.
String auditMask = "usedInsertionOrdersCount,usedLineItemsCount,negativeKeywordListsCount";

// Configure the audit request.
Advertisers.Audit request =
    service.advertisers().audit(advertiser-id);

// Set the read mask for the request.
request.setReadMask(auditMask);

// Execute the request.
AuditAdvertiserResponse response = request.execute();

// Print resulting advertiser used entity counts.
System.out.println("Advertiser Audit:");

if (response.getUsedInsertionOrdersCount() != null) {
  System.out.printf("Used Insertion Orders: %s of 9999 \n",
      response.getUsedInsertionOrdersCount());
} else {
  System.out.println("Used Insertion Orders: 0 of 9999");
}

if (response.getUsedLineItemsCount() != null) {
  System.out.printf("Used Line Items: %s of 9999 \n",
      response.getUsedLineItemsCount());
} else {
  System.out.println("Used Line Items: 0 of 9999");
}

if (response.getNegativeKeywordListsCount() != null) {
  System.out.printf("Negative Keyword Lists: %s of 20 \n",
      response.getNegativeKeywordListsCount());
} else {
  System.out.println("Negative Keyword Lists: 0 of 20");
}

Python

# Create read mask to restrict audit results to
# the relevant account limits.
audit_mask = 'usedInsertionOrdersCount,usedLineItemsCount,negativeKeywordListsCount'

# Build and execute request.
response = service.advertisers().audit(
    advertiserId=advertiser-id,
    readMask=audit_mask
).execute()

# Print resulting advertiser used entity counts.
print('Advertiser audit:')

if 'usedInsertionOrdersCount' in response:
  print('Used Insertion Orders: %s of 9999' %
        response['usedInsertionOrdersCount'])
else:
  print('Used Insertion Orders: 0 of 9999')

if 'usedLineItemsCount' in response:
  print('Used Line Items: %s of 9999' % response['usedLineItemsCount'])
else:
  print('Used Line Items: 0 of 9999')

if 'negativeKeywordListsCount' in response:
  print('Negative Keyword Lists: %s of 20' % response['negativeKeywordListsCount'])
else:
  print('Negative Keyword Lists: 0 of 20')

PHP

// Create read mask to restrict audit results to the
// relevant account limits.
$optParams = array(
    'readMask' => 'usedInsertionOrdersCount,usedLineItemsCount,negativeKeywordListsCount'
);

// Call the API, getting the account limit audit counts for the identified
// advertiser.
$response = $this->service->advertisers->audit(
    advertiser-id,
    $optParams
);

# Print resulting advertiser used entity counts.
print('Advertiser audit:\n');

if ($response->getUsedInsertionOrdersCount()) {
    printf(
        'Used Insertion Orders: %s of 9999\n',
        $response->getUsedInsertionOrdersCount()
    );
} else {
    print('Used Insertion Orders: 0 of 9999\n');
}

if ($response->getUsedLineItemsCount()) {
    printf(
        'Used Line Items: %s of 9999\n',
        $response->getUsedLineItemsCount()
    );
} else {
    print('Used Line Items: 0 of 9999\n');
}

if ($response->getNegativeKeywordListsCount()) {
    printf(
        'Negative Keyword Lists: %s of 20\n',
        $response->getNegativeKeywordListsCount()
    );
} else {
    print('Negative Keyword Lists: 0 of 20\n');
}

Optimize entity counts

To ensure that account limits are not reached, delete or archive resources when they're no longer needed.

Delete unused negative keyword lists

If an advertiser audit shows that the count of negative keyword lists under your advertiser is nearing the limit, delete negative keyword lists that are not being used in order to make room to create new negative keyword lists.

These negative keyword lists can be identified by comparing assigned negative keyword list targeting options to existing negative keyword lists and then deleted using advertisers.negativeKeywordLists.delete.

Here's an example of how to identify and delete a given advertiser's negative keyword lists that are not currently being used:

Java

// Create constants for input variables.
Long ADVERTISER_ID = advertiser-id

// Create empty set for negative keyword lists (NKLs)
// that are currently used in targeting.
Set<String> targetedNKLs = new HashSet<String>();

// Build line item list request
LineItems.List request =
    service
        .advertisers()
        .lineItems()
        .list(ADVERTISER_ID);

// Create the line item list response, assigned targeting option list
// response, and nextPageToken variables.
ListLineItemsResponse response;
ListLineItemAssignedTargetingOptionsResponse atoListResponse;
String nextPageToken = null;

do {
  // Create and execute the list request.
  response = request.setPageToken(nextPageToken).execute();

  // Check if response is empty.
  if (response.isEmpty()) {
    System.out.printf(
        "List request returned no line items for Advertiser ID %s.%n",
        ADVERTISER_ID);
    break;
  }

  // Iterate over retrieved line items and retrieve all assigned negative
  // keyword list targeting.
  for (LineItem lineItem : response.getLineItems()) {
    atoListResponse =
        service
            .advertisers()
            .lineItems()
            .targetingTypes()
            .assignedTargetingOptions()
            .list(
                ADVERTISER_ID,
                lineItem.getLineItemId(),
                "TARGETING_TYPE_NEGATIVE_KEYWORD_LIST"
            ).execute();

    // Check if response is empty.
    if (atoListResponse.isEmpty()) {
      continue;
    }

    // Add all negative keyword list used in targeting to set.
    for (AssignedTargetingOption ato : atoListResponse.getAssignedTargetingOptions()) {
      targetedNKLs.add(ato.getAssignedTargetingOptionId());
    }
  }

  // Update the next page token.
  nextPageToken = response.getNextPageToken();
} while (!Strings.isNullOrEmpty(nextPageToken));

// Retrieve all negative keyword lists under the given advertiser.
ListNegativeKeywordListsResponse nklListResponse =
    service
        .advertisers()
        .negativeKeywordLists()
        .list(
            ADVERTISER_ID
        ).execute();

// Iterate through all available negative keyword lists and delete those
// that are not in the set negative keyword lists used in targeting.
if (nklListResponse.isEmpty()) {
  System.out.printf(
      "Advertiser ID %s has no negative keyword lists.%n",
      ADVERTISER_ID
  );
} else {
  for (NegativeKeywordList nkl : nklListResponse.getNegativeKeywordLists()) {
    if (!targetedNKLs.contains(Long.toString(nkl.getNegativeKeywordListId()))) {
      service
          .advertisers()
          .negativeKeywordLists()
          .delete(
              ADVERTISER_ID,
              nkl.getNegativeKeywordListId()
          ).execute();
      System.out.printf(
          "Unused negative keyword list %s deleted.%n",
          nkl.getNegativeKeywordListId());
    }
  }
}

Python

# Create constants for input variables.
ADVERTISER_ID = advertiser-id

# Create empty set for negative keyword lists (NKLs)
# that are currently used in targeting.
targetedNKLs = set()

# Create the page token variable for list request loop.
nextPageToken = ""

# Iterate through all line items, retrieve their NKL targeting, and save the
# NKLs currently used in targeting.
while True:
  # Request the line items list.
  lineItemListResponse = service.advertisers().lineItems().list(
      advertiserId=ADVERTISER_ID,
      pageToken=nextPageToken
  ).execute()

  # Check if response is empty.
  if not lineItemListResponse:
    print('List request returned no line items for advertiser ID %s.'
          % ADVERTISER_ID)
    break

  # Iterate over retrieved line items.
  for lineItem in lineItemListResponse['lineItems']:
    # Request the NKL targeting assigned to the line item.
    targetingListResponse = service.advertisers().lineItems()\
        .targetingTypes().assignedTargetingOptions().list(
            advertiserId=ADVERTISER_ID,
            lineItemId=lineItem['lineItemId'],
            targetingType="TARGETING_TYPE_NEGATIVE_KEYWORD_LIST"
        ).execute()

    # Check if no NKLs are used in targeting.
    if not targetingListResponse:
      continue

    # Iterate through assigned NKL targeting options, add them to set.
    for targetingOption in targetingListResponse['assignedTargetingOptions']:
      targetedNKLs.add(targetingOption['assignedTargetingOptionId'])

  # Break out of loop if there is no next page.
  if 'nextPageToken' not in lineItemListResponse:
    break

  # Update the next page token.
  nextPageToken = response['nextPageToken']

# Request the NKL list.
nklListResponse = service.advertisers().negativeKeywordLists().list(
    advertiserId=ADVERTISER_ID
).execute()

# Iterate through NKLs under advertiser and delete if they are not present
# in the list of NKLs currently used in targeting.
if not nklListResponse:
  print('Advertiser ID %s has no negative keyword lists.'
        % ADVERTISER_ID)
else:
  for nkl in nklListResponse['negativeKeywordLists']:
    if nkl['negativeKeywordListId'] not in targetedNKLs:
      service.advertisers().negativeKeywordLists().delete(
          advertiserId=ADVERTISER_ID,
          negativeKeywordListId=nkl['negativeKeywordListId']
      ).execute()
      print('Unused negative keyword list %s deleted.' % nkl["name"])

PHP

// Create constants for input variables.
const ADVERTISER_ID = advertiser-id;

// Create empty array for negative keyword lists (NKLs)
// that are currently used in targeting.
$targetedNKLs = array();

// Create the line item list response, assigned targeting option list
//response, and page token variables.
$response = null;
$atoListResponse = null;
$nextPageToken = null;

do {
    // Build the query params for the line item list request
    $optParams = array('pageToken' => $nextPageToken);

    // Call the API, retrieving all line items under the advertiser.
    $response = $this
        ->service
        ->advertisers_lineItems
        ->listAdvertisersLineItems(ADVERTISER_ID, $optParams);

    if (empty($response->getLineItems())) {
        printf(
            "List request returned no line items for Advertiser ID %s.\n",
            ADVERTISER_ID
        );
        break;
    }

    // Iterate over retrieved line items and retrieve all assigned negative
    // keyword list targeting options.
    foreach ($response->getLineItems() as $lineItem) {
        $atoListResponse = $this
            ->service
            ->advertisers_lineItems_targetingTypes_assignedTargetingOptions
            ->listAdvertisersLineItemsTargetingTypesAssignedTargetingOptions(
                ADVERTISER_ID,
                $lineItem->getLineItemId(),
                "TARGETING_TYPE_NEGATIVE_KEYWORD_LIST"
            );

        // Add each negative keyword list ID to array as key to associative
        // array
        foreach ($atoListResponse->getAssignedTargetingOptions() as $option) {
            $targetedNKLs[$option->getAssignedTargetingOptionId()] = true;
        }

    }

    // Update the next page token.
    $nextPageToken = $response->getNextPageToken();

} while (!empty($nextPageToken));

// Call the API, retrieving all negative keyword lists under the advertiser
$nklListResponse = $this
    ->service
    ->advertisers_negativeKeywordLists
    ->listAdvertisersNegativeKeywordLists(ADVERTISER_ID);

// Iterate through existing negative keyword lists and check if they are in
// the associative array of negative keyword lists used in targeting.
// If not, delete the negative keyword list.
if (empty($nklListResponse->getNegativeKeywordLists())) {
    printf(
        "Advertiser ID %s has no negative keyword lists.\n",
        ADVERTISER_ID
    );
} else {
    foreach ($nklListResponse->getNegativeKeywordLists() as $nkl) {
        if (!array_key_exists($nkl->getNegativeKeywordListId(), $targetedNKLs)) {
            $this
                ->service
                ->advertisers_negativeKeywordLists
                ->delete(
                    ADVERTISER_ID,
                    $nkl->getNegativeKeywordListId()
                );
            printf(
                "Unused negative keyword list %s was deleted.\n",
                $nkl->getNegativeKeywordListId()
            );
        }
    }
}