Frequency management tasks and endpoints

The following sections list the endpoints for managing the frequency framework elements and provide high-level guidelines for using them:

• Counters
• Increments
• Bid lists

For common use cases and setup instructions, see the guides for Frequency caps, goals, and bid adjustments.

TIP: For basic configurations, it is most efficient to use the frequency configuration endpoints, which allow you to set up counters, increments, and bid lists in one step.

Counters

A counter is a container that holds the user’s frequency count information (the number of times the user has seen the ad) and defines the time interval (the ResetIntervalInMinutes field) after which the counter is reset.

Here's what you need to know about counters:

• Counters are the key frequency setting. Querying frequency configurations requires a valid counter ID.
• Use as few counters as possible to cover unique combinations of ResetIntervalInMinutes and Increments in your strategy.
• Counters retain user counts for approximately two weeks after a campaign ends. This may affect your data if you decide to reuse counters.
• Delete any counters that are no longer needed. Deleting a counter will also delete any increment links that reference that counter.

Creating counters

The following table lists the endpoints you can use to create counters.

Retrieving counters

The following table lists the endpoints you can use to retrieve counter information.

Look up frequency configuration for a counter

To view the frequency information for a specific counter, include its ID as the path parameter in a GET /v3/frequency/config/{counterId} request.

For example, for a counter with the ID of 2gbda7q, a GET /v3/frequency/config/2gbda7q request may return the following configuration details, which include an ad group that increments the counter and a bid list with which the frequency configuration is associated.

{
   "Counter":{
      "CounterId":"2gbda7q",
      "AdvertiserId":"7ftzaer",
      "ResetIntervalInMinutes":300,
      "CounterName":"Basic Frequency - AG: 8hbtm7p, Reset: 300",
      "CounterAttribute":"None"
   },
   "Increments":{
      "AdGroups":[
         "qzjt6yn"
      ]
   },
   "BidLists":[
      {
         "BidListId":"62220626",
         "Name":"Default Frequency Cap List",
         "BidListOwner":"AdGroup",
         "BidListOwnerId":"qzjt6yn",
         "NumberOfBidLines":1,
         "BidListAdjustmentType":"TargetList",
         "AssociatedAdGroups":[
            "qzjt6yn"
         ],
         "BidLines":[
            {
               "Range":{
                  "Min":0,
                  "Max":1
               },
               "VolumeControlPriority":"Neutral",
               "BidAdjustment":1.000000
            }
         ]
      }
   ]
}

Updating counters

The following table lists the endpoints you can use to update counters.

Deleting counters

The following table lists the endpoint you can use to delete counters.

Increments

Increments are entities (partners, advertisers, campaigns, and ad groups) that serve impressions to users and increase the user's frequency count for the associated counter.

Descendant entities affect increment the counters of their higher-level entities set as increments. For example, a partner set as an increment would increase the counter any time a user sees an ad for any ad groups for any of its advertisers' campaigns.

TIP: Use the entity-level inheritance to set up frequency increments at the appropriate levels and reduce manual tasks.

For example, to increment frequency counts for every ad group in a campaign, set the campaign to increment the counter rather than individual ad groups. If an ad group is added to the campaign after frequency is set up, the campaign-level increment will apply to the new ad group, whereas if individual ad groups are specified as increments, the new ad group will need to be manually added.

Creating increments

Retrieving increments

The endpoints listed below return all increments as a list of CounterIds in the Increments array. To retrieve individual counter details, use the GET /v3/frequency/counter/{counterId} endpoint.

Updating increments

Removing increments

Bid lists

Use bid lists to apply frequency caps, frequency goals, and bid adjustments to partners, advertisers, campaigns, and ad groups by specifying the counter to use and configuring the relevant adjustments. For details, see Frequency bid adjustments.