Discard
GuidesAPI ReferenceChangelogDiscussions
GuidesAPI ReferenceChangelogDiscussionsLog In

Anatomy of an Ad Set

Ad Set Example

The following is an example of the JSON data structure of an Ad Set.

Additional details about the individual attributes of Ad Sets can be found below.

 

{
    "type": "ReadAdSet",
    "id": "123467",
    "attributes": {
        "name": "Campaign A",
        "advertiserId": "12345",
        "destinationEnvironment": "app",
        "mediaType": "Display",
        "datasetId": "6789",
        "campaignId": "1485",
        "schedule": {
            "startDate": "2018-07-04T00:00:00Z",
            "endDate": "2018-07-26T00:00:00Z",
            "activationStatus": "on",
            "deliveryStatus": "live"
        },
        "bidding": {
            "bidAmount": 0.9,
            "bidStrategy": "Conversions",
            "costController": "CPC",
        },
        "targeting": {
            "frequencyCapping": {
                "frequency": "hourly",
                "maximumImpressions": 3
            },
            "geoLocation": {
                "countries": {"values": ["FR"], "operand": "in"},
                "subdivisions":  {"values": ["FR-01", "FR-38"], "operand": "notIn"},
                "zipCodes":  null
            },
            "deliveryLimitations": {
                "devices": ["mobile", "tablet"],
                "operatingSystems": ["ios"],
                "environments": []
            }
        },
        "budget": {
            "budgetStrategy": "capped",
            "budgetRenewal": "daily",
            "budgetDeliverySmoothing": "accelerated",
            "budgetDeliveryWeek": "mondayToSunday",
            "budgetAmount": {"value": 123.45}
        }
    }
}

 

Ad Set General Info

name
The Ad Set name, set by the advertiser.

destinationEnvironment
Read-only. The environment that an ad click will lead a user to.

mediaType
The type of media the ad set will deliver on. Can be Display (default) or Video

datasetId
Data Set Id associated with the specified advertiser ID. See Datasets for how to find datasets associated to advertisers.

campaignId
Id of the marketing campaign associated to the ad set. See Search for Campaigns for how to search for campaigns.

Ad Set Schedule

 
schedule.startDate
ISO 8601 format. If defined, it must always be later than the schedule.endDate. Once set, it is not possible to set the value back to null.

schedule.endDate
ISO 8601 format. null by default. (null is a valid value.)

schedule.activationStatus
Can be on or off. off by default. Set by the advertiser, this represents the intent to deliver ads. See Start and Stop Ad Sets for how to change this value.

schedule.deliveryStatus

The initial value for a newly created Ad Set is draft. This is a computed value and is read-only. The table below enumerates deliveryStatus field and explains its relation with activationStatus field.

deliveryStatus

Description

activationStatus

Inactive

An Ad Set is not delivering because it has been paused by a user.

An inactive Ad Set won't deliver unless a client explicitly activates it via UI or API.

off

Draft

An Ad Set is newly created and was never activated.

An inactive Ad Set won't deliver unless a client explicitly activates it via UI or API.

off

Pausing

An Ad Set was just deactivated by a user but is not paused yet.

off

Live

An Ad Set is delivering right now.

on

Scheduled

Activated with the activation date in the future. Will automatically deliver on the set activation date. In other words, on the set activation date the status of an Ad Set becomes Live.

on

Ended

Activated but with the Ad Set end date in the past. Hence the Ad Set is not delivering right now.
The Ad Set Will automatically deliver if the Ad Set end date is updated to a future date. Once the update is made the status of an Ad Set becomes Live.

on

Not Live

Activated, but not Live right now due to some transitory cause.

Examples:

  • Ad Set has ran out of allocated budget for its current periodicity.
  • Contact List Audience has been updated but not computed yet

on

Archived

An archived Ad Set can't be re-activated. The historical data is preserved according to the latest data retention policy.

N/A

🚧

activationStatus vs deliveryStatus

deliveryStatus is a computed value. It is affected by factors other than the value of activationStatus, such as budget consumption, start date, and end date.

 

Ad Set Bidding

 

bidding.bidAmount
Decimal value target relating to the bidStrategy specified. May be null for strategies that do not require a target value.

bidding.bidStrategy
The intended optimization for the Ad Set. Can be actions, clicks, conversions, displays, installs, revenue, storeConversions, value, viewedImpressions, visits or CompletedVideoViews (only when mediaType is set to Video).

bidding.costController
How spend is controlled and optimized. Can be COS (Cost of Sale), CPC (Cost per Click), CPI (Cost per Install), CPM (Cost per Mille), CPO (Cost per Order), CPSV (Cost per Site Visit), CPV (Cost per View), or dailyBudget.

Ad Set Targeting

 

targeting.frequencyCapping.maximumImpressions
Integer value. The maximum impressions allowed for the specified frequencyCapping.frequency.

targeting.frequencyCapping.frequency
The period by which the maximum impression limit is calculated. Can be hourly, daily, lifetime, or advanced (for custom set-ups configured by Criteo). It is not possible to set the value to advanced.

targeting.geoLocation.countries
Contains an array of values, two letter country codes, ISO-3166 format. Also specifies an operand which can be in or notIn depending on the desired behavior for the values.

targeting.geoLocation.subdivisions
Contains an array of values, geographical subdivisions following ISO-3166 format. Also specifies an operand which can be in or notIn depending on the desired behavior for the values.

targeting.geoLocation.zipCodes
Contains an array of values, zip codes. Also specifies an operand which can be in or notIn depending on the desired behavior for the values.

🚧

Geolocation Targeting

Geolocation settings do not support an empty array for their values. If a geolocation setting like geoLocation.countries is null, then the filter is inactive. Otherwise, the filter is active and must have a non-empty list for values.

targeting.deliveryLimitations.devices
List of device types that the Ad Set should target. Can contain desktop, tablet, mobile and other.

targeting.deliveryLimitations.operatingSystems
List of operating systems that the Ad Set should target. Can contain android, ios, and other.

targeting.deliveryLimitations.environments
List of display environments that the Ad Set should target. Can contain inApp and web.

Ad Set Budget

📘

Budgets Are Now Mutable

Budgets were read-only in the API version 2021.04. This has changed and the Budget entities are now mutable in all versions.

 

budget.budgetStrategy
Whether budget is capped or not. Can be capped or uncapped.

budget.budgetRenewal
The cadence of budget reneweal. Can be daily, monthly, lifetime, or undefined.

budget.budgetDeliverySmoothing
The pace at which budget can be spent. Can be accelerated or standard.

budget.budgetDeliveryWeek
The seven day period for budget delivery. Can be mondayToSunday, tuesdayToMonday, wednesdayToTuesday, thursdayToWednesday, fridayToThursday, saturdayToFriday, or sundayToSaturday.

budget.budgetAmount
A decimal value showing the remaining budget value for Ad Sets with Capped budget strategies. For uncapped budgets, the value will be null.


What’s Next

Learn how to search for existing Ad Sets using filters

Did this page help you?