GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog 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",
        "campaignId": "12345",
        "destinationEnvironment": "app",
        "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

The Ad Set name, set by the advertiser.

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

Ad Set Schedule

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.

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

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.

Can be draft, inactive, live, notLive, pausing, paused, scheduled, ended, notDelivering, or archived. The initial value for a newly created Ad Set is draft. This is a computed value and is read-only.


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


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

The intended optimization for the Ad Set. Can be actions, clicks, conversions, displays, installs, revenue, storeConversions, value, viewedImpressions or visits.

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


Integer value. The maximum impressions allowed for the specified 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.

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.

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.

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.

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

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

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.


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

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

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

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

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 Ad Sets