Marketing API Version

Ad Set

Note: Ad Set vs. Ad Campaign
Prior to July 2014 ad sets were referred to as 'campaigns'. When using ad sets in API calls the parameter may be referred to as 'adcampaign'. A campaign contains one or more ad sets.

Limits

The following are the limits on ad sets

LimitValue

Maximum number of ad sets per regular ad account

5000 non deleted ad sets

Maximum number of ad sets per bulk ad account

10000 non deleted ad sets

Maximum number of ads per ad set

50 non deleted ad groups

Reading

An ad set is a group of ads that share the same daily or lifetime budget, schedule, bid type, bid info, and targeting data. Ad sets enable you to group ads according to your criteria, and you can retrieve the ad-related statistics that apply to a set.

Permissions

Developers usually request these permissions for this endpoint:

  • ads_management
  • business_management

Examples

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;

$adset = new AdSet('<AD_SET_ID>', 'act_<AD_ACCOUNT_ID>');
$adset->read(array(
  AdSetFields::NAME,
  AdSetFields::CAMPAIGN_STATUS,
));

echo $adset->name; // Outputs name of adset.
echo $adset->campaign_status; // Outputs status of adset.
from facebookads.objects import AdSet

adset = AdSet(fbid='<AD_SET_ID>', parent_id='act_<AD_ACCOUNT_ID>')
adset.remote_read(fields=[
    AdSet.Field.name,
    AdSet.Field.status,
])

# Output adset name.
print adset[AdSet.Field.name]
# Output adset status.
print adset[AdSet.Field.status]
curl -G \
-d "fields=name,campaign_status" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_SET_ID>"

To retrieve date-time related fields in a UNIX timestamp format, use the date_format parameter:

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;

$adset = new AdSet(<AD_SET_ID>);
$fields = array(
  AdSetFields::START_TIME,
);
$params = array(
  'date_format' => 'U',
);
$adset->read($fields, $params);

// Print out start time in UNIX timestamp format.
echo $adset->start_time;
from facebookads.objects import AdSet

adset = AdSet(<AD_SET_ID>)
fields = [AdSet.Field.start_time]
params = {'date_format': 'U'}
adset.remote_read(fields=fields, params=params)

# Print out start time in UNIX timestamp format.
print adset[AdSet.Field.start_time]
curl -G \
-d "fields=start_time" \
-d "date_format=U" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_SET_ID>"

To retrieve information for multiple ad sets:

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;

$adset_ids = array(<AD_SET_ID_1>, <AD_SET_ID_2>, <AD_SET_ID_3>);
$fields = array(AdSetFields::NAME, AdSetFields::CAMPAIGN_STATUS);
$adsets = AdSet::readIds($adset_ids, $fields);

// This will output the name of all fetched ad sets.
foreach ($adsets as $adset) {
  echo $adset->name;
}
curl -G \
-d "ids=<AD_SET_1>, <AD_SET_2>, <AD_SET_3>" \
-d "fields=name,campaign_status" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/"

To read all ad sets from one ad campaign:

use FacebookAds\Object\AdCampaign;
use FacebookAds\Object\Fields\AdSetFields;

$adcampaign = new AdCampaign($adcampaign_id);
$adsets = $adcampaign->getAdSets(array(
  AdSetFields::NAME,
  AdSetFields::CAMPAIGN_STATUS
));

// This will output the name of all fetched ad sets.
foreach ($adsets as $adset) {
  echo $adset->name;
}
from facebookads.objects import AdCampaign, AdSet

adcampaign = AdCampaign('<AD_CAMPAIGN_GROUP_ID>')
adsets = adcampaign.get_ad_sets([
    AdSet.Field.name,
    AdSet.Field.status,
])

# This will output the name of all fetched ad sets.
for adset in adsets:
    print adset[AdSet.Field.name]
curl -G \
-d "fields=name,campaign_status" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_CAMPAIGN_ID>/adcampaigns"

To read all ad sets from one ad account:

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdSetFields;

$account = new AdAccount('<AD_ACCOUNT_ID>');
$adsets = $account->getAdSets(array(
  AdSetFields::NAME,
  AdSetFields::CAMPAIGN_STATUS
));

// This will output the name of all fetched ad sets.
foreach ($adsets as $adset) {
  echo $adset->name;
}
from facebookads.objects import AdAccount, AdSet

account = AdAccount('<AD_ACCOUNT_ID>')
adsets = account.get_ad_sets([
    AdSet.Field.name,
    AdSet.Field.status,
])

# This will output the name of all fetched ad sets.
for adset in adsets:
    print adset[AdSet.Field.name]
curl -G \
-d "fields=name,campaign_status" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adcampaigns"

To read the start_time, end_time (in a UNIX timestamp format), campaign_status, and campaign_group_id fields.

use FacebookAds\Object\AdSet;

$adset = new AdSet($adset_id);
$params = array(
  'date_format' => 'U',
);
$adset->read(array(
  'start_time',
  'end_time',
  'campaign_status',
  'campaign_group_id',
), $params);

echo $adset->campaign_status;
from facebookads.objects import AdSet

adset = AdSet('<AD_SET_ID>')
params = {
    'date_format': 'U',
}
adset.remote_read(fields=[
    AdSet.Field.start_time,
    AdSet.Field.end_time,
    AdSet.Field.status,
    AdSet.Field.campaign_group_id,
], params=params)

print adset[AdSet.Field.status]
curl -G \
-d "date_format=U" \
-d "fields=start_time,end_time,campaign_status,campaign_group_id" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_SET_ID>"

Response:
{
  "campaign_group_id": 6012801070748,
  "start_time": 1377891607,
  "end_time": 1377993600,
  "campaign_status": "ACTIVE",
  "id":" 6011994216748"
}

To read the names of ad sets with status paused in an ad account

use FacebookAds\Object\AdAccount;

$account = new AdAccount($account_id);
$adsets = $account->getAdSets(array(
  'name',
), array(
  'campaign_status' => array(
    'PAUSED'
  ),
);

// Output adset names.
foreach ($adsets as $adset) {
  echo $adset->name;
}
from facebookads.objects import AdAccount

account = AdAccount('<AD_ACCOUNT_ID>')
params =  {
    'campaign_status': ['PAUSED'],
}
adsets = account.get_ad_sets([AdSet.Field.name], params=params)

# Output adset names.
for adset in adsets:
    print adset[AdSet.Field.name]
curl -G \
-d "campaign_status=['PAUSED']" \
-d "fields=name" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/act_<AD_ACCOUNT_ID>/adcampaigns"

Response:
{
  "data":[
    {"name":"AdSet 1","id":"601199448"},
    {"name":"AdSet 1","id":"601084228"},
    {"name":"AdSet 1","id":"601022148"},
    {"name":"AdSet 1","id":"601023738"},
  ],
  "paging":{"cursors":{
    "after":"NjAwNzc4NjI5Mjk0OA==",
    "before":"NjAxMTk5NDIxNjc0OA=="
  }},
  "count":4,
  "limit":100,
  "offset":0
}

To read the end_time of multiple ad sets.

use FacebookAds\Object\AdSet;

$adsets = AdSet::readIds(
  array($adset_id1, $adset_id2),
  array('end_time'),
);

// Output end times.
foreach ($adsets as $adset) {
  echo $adset->end_time;
}
curl -G \
-d "ids=<AD_SET_ID1>,<AD_SET_ID2>" \
-d "fields=end_time" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/"
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

This endpoint doesn't have any parameters.

Fields

FieldDescription

id

numeric string

Ad set ID

account_id

numeric string

Ad Account ID

adlabels

Ad Labels associated with this ad set

adset_schedule

Ad set schedule, representing a delivery schedule for a single day

attribution_window_days

unsigned int32

Conversion attribution window, representing days in time of the attribution window length, 1, 7 or 28 days for pixels and 1 day for others. This parameter is only available with the OFFSITE_CONVERSIONS or APP_INSTALLS optimization goal.

bid_amount

unsigned int32

Bid amount for this ad set, defined as your true value bid based on optimization_goal. This field is not available if is_autobid is true or when bid_info is returned. The bid amount's unit is cent for currencies like USD, EUR, and the basic unit for currencies like JPY, KRW. The bid amount for ads with IMPRESSION, REACH as billing_event is per 1,000 occurrences, and that for ads with other billing_event is for each occurrence.

bid_info

map<string, unsigned int32>

Map of bid objective to bid value. This field is not available if is_autobid is true.

billing_event

enum {APP_INSTALLS, CLICKS, IMPRESSIONS, LINK_CLICKS, OFFER_CLAIMS, PAGE_LIKES, POST_ENGAGEMENT, VIDEO_VIEWS}

The billing event that this adset is using:
APP_INSTALLS: Pay when people install your app.
CLICKS: Pay when people click anywhere in the ad.
IMPRESSIONS: Pay when the ads are shown to people.
LINK_CLICKS: Pay when people click on the link of the ad.
OFFER_CLAIMS: Pay when people claim the offer.
PAGE_LIKES: Pay when people like your page.
POST_ENGAGEMENT: Pay when people engage with your post.
VIDEO_VIEWS: Pay when people watch videos.

budget_remaining

numeric string

Remaining budget

campaign

The campaign that contains this ad set

campaign_id

numeric string

Campaign ID

configured_status

enum {ACTIVE, PAUSED, DELETED, ARCHIVED}

The status set at the ad set level. It can be different from the effective status due to its parent campaign. Prefer using 'status' instead of this.

created_time

datetime

Created time

creative_sequence

list<numeric string>

Order of the adgroup sequence to be shown to users

daily_budget

numeric string

The daily budget of the set defined in your account currency.

effective_status

enum {ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED}

The effective status of the ad set, which can be either its own status or caused by its parent campaign.

end_time

datetime

End time, in UTC UNIX timestamp

frequency_cap

unsigned int32

The number of times this ad will show per day.

frequency_cap_reset_period

unsigned int32

The number of hours that will pass before resetting the frequency capping.

frequency_control_specs

An array of frequency control specs for this ad set. As there is only one event type supported currently, this array would have no more than one element. Only available in ad sets of campaigns with BRAND_AWARENESS as objective and REACH as optimization_goal. These cannot be used in Reach & Frequency campaigns.

instagram_actor_id

numeric string

The Instagram actor id used for DCO ad on Instagram.

is_autobid

bool

Did the advertiser express the intent to bid automatically. This field is not available if bid_info or bid_amount is returned.

is_average_price_pacing

bool

Did the advertiser express the intent to use average price pacing

lifetime_budget

numeric string

The lifetime budget of the set defined in your account currency.

lifetime_frequency_cap

unsigned int32

Lifetime frequency cap

lifetime_imps

int32

Lifetime impressions. Available only for campaigns with buying_type=FIXED_CPM

name

string

Name of ad set

optimization_goal

enum {NONE, APP_INSTALLS, BRAND_AWARENESS, CLICKS, ENGAGED_USERS, EXTERNAL, EVENT_RESPONSES, IMPRESSIONS, LEAD_GENERATION, LINK_CLICKS, OFFER_CLAIMS, OFFSITE_CONVERSIONS, PAGE_ENGAGEMENT, PAGE_LIKES, POST_ENGAGEMENT, REACH, SOCIAL_IMPRESSIONS, VIDEO_VIEWS, APP_DOWNLOADS}

Which optimization goal this ad set is using:
NONE: Only available in read mode for campaigns created pre v2.4
APP_INSTALLS: Optimize for people more likely to install your app.
BRAND_AWARENESS: Optimize to reach the most number of users who are likely to spend at least a minimum amount of time on the image or video.
CLICKS: Optimize for people more likely to click anywhere in the ad.
ENGAGED_USER: Optimize for people more likely to take a particular action in your app
EXTERNAL: FBX only
EVENT_RESPONSES: Optimize for people more likely to attend your event
IMPRESSIONS: Show the ads as many times as possible
LINK_CLICKS: Optimize for people more likely to click in the link of the ad.
OFFER_CLAIMS: Optimize for people more likely to claim the offer.
OFFSITE_CONVERSION: Optimize for people more likely to make a conversion in the site
PAGE_LIKES: Optimize for people more likely to like your page.
PAGE_ENGAGEMENT: Optimize for people more likely to engage with your page.
POST_ENGAGEMENT: Optimize for people more likely to engage with your post.
REACH: Optimize to reach the most unique users of each day or interval specified in frequency_control_specs.
SOCIAL_IMPRESSIONS: Increase the number of impressions with social context.
I.e. with the names of one or more of the user's friends attached to the ad who have already liked the page or installed the app.
VIDEO_VIEWS: Optimize for people more likely to watch videos.LEAD_GENERATION: Optimize for people more likely to fill out a lead generation form.

pacing_type

list<string>

Defines the pacing type, standard or using ad scheduling

promoted_object

The object this ad set is promoting across all its ads.

recommendations

If there are recommendations for this ad set, this field includes them. Otherwise, will not be included in the response. (This field is not included in redownload mode.)

recurring_budget_semantics

bool

If this field is true, your daily spend may be more than your daily budget while your weekly spend will not exceed 7 times your daily budget. More details explained in the Ad Set Budget document. If this is false, your amount spent daily will not exceed the daily budget. This field is not applicable for lifetime budgets.

rf_prediction_id

id

Reach and frequency prediction ID

rtb_flag

bool

Whether this ad set is using RTB or not

start_time

datetime

Start time, in UTC UNIX timestamp

status

enum {ACTIVE, PAUSED, DELETED, ARCHIVED}

Ad set status

targeting

Targeting

time_based_ad_rotation_id_blocks

list<list<integer>>

Specify ad creative that displays at custom date ranges in a campaign as an array. A list of Adgroup IDs. The list of ads to display for each time range in a given schedule. For example display first ad in Adgroup for first date range, second ad for second date range, and so on. You can display more than one ad per date range by providing more than one ad group ID per array. For example set time_based_ad_rotation_id_blocks to [[1], [2, 3], [1, 4]]. On the first date range show ad 1, on the second date range show ad 2 and ad 3 and on the last date range show ad 1 and ad 4. Use with time_based_ad_rotation_intervals to specify date ranges.

time_based_ad_rotation_intervals

list<unsigned int32>

Date range when specific ad creative displays during a campaign. Provide date ranges in an array of UNIX timestamps where each timestamp represents the start time for each date range. For example a 3-day campaign from May 9 12am to May 11 11:59PM PST can have three date ranges, the first date range starts from May 9 12:00AM to May 9 11:59PM, second date range starts from May 10 12:00AM to May 10 11:59PM and last starts from May 11 12:00AM to May 11 11:59PM. The first timestamp should match the campaign start time. The last timestamp should be at least 1 hour before the campaign end time. You must provide at least two date ranges. All date ranges must cover the whole campaign length, so any date range cannot exceed campaign length. Use with time_based_ad_rotation_id_blocks to specify ad creative for each date range.

updated_time

datetime

Updated time

use_new_app_click

bool

If set, allows Mobile App Engagement ads to optimize for LINK_CLICKS

Edges

EdgeDescription

activities

The activities of this ad set

adcreatives

The creatives of this ad set

ads

The ads under this ad set

asyncadrequests

Async ad requests for this ad set

insights

Insights on advertising performance of this ad set

targetingsentencelines

The targeting description sentence for this ad set

conversions

Reference document for using Facebook Marketing APIs to get conversion stats on your Facebook ads, ad sets, and accounts.

stats

Reference document for using Facebook Marketing APIs to get ad statistics on impressions, clicks, performance, and more

Validation Rules

ErrorDescription
100Invalid parameter
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
278Reading advertisements requires an access token with the extended permission ads_read
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API
272This Ads API call requires the user to be admin of the application
273This Ads API call requires the user to be admin of the ad account

Creating

As of 2.8, Instant Articles is now a separate ads placement, so that advertisers can enable or disable showing ads as Instant Article. See Targeting Specs, Device, Publisher and Positions.

Examples

Create an ad set with a daily budget:

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;
use FacebookAds\Object\Fields\TargetingFields;
use FacebookAds\Object\Values\AdSetBillingEventValues;
use FacebookAds\Object\Targeting;
use FacebookAds\Object\Values\AdSetOptimizationGoalValues;

$adset = new AdSet(null, 'act_<AD_ACCOUNT_ID>');
$adset->setData(array(
  AdSetFields::NAME => 'My Ad Set',
  AdSetFields::OPTIMIZATION_GOAL => AdSetOptimizationGoalValues::REACH,
  AdSetFields::BILLING_EVENT => AdSetBillingEventValues::IMPRESSIONS,
  AdSetFields::BID_AMOUNT => 2,
  AdSetFields::DAILY_BUDGET => 1000,
  AdSetFields::CAMPAIGN_ID => <CAMPAIGN_ID>,
  AdSetFields::TARGETING => (new Targeting())->setData(array(
    TargetingFields::GEO_LOCATIONS => array(
      'countries' => array('US'),
    ),
  )),
));
$adset->create(array(
  AdSet::STATUS_PARAM_NAME => AdSet::STATUS_PAUSED,
));
from facebookads.adobjects.adset import AdSet
from facebookads.adobjects.targeting import Targeting

adset = AdSet(parent_id='act_<AD_ACCOUNT_ID>')
adset.update({
    AdSet.Field.name: 'My Ad Set',
    AdSet.Field.campaign_id: <CAMPAIGN_ID>,
    AdSet.Field.daily_budget: 1000,
    AdSet.Field.billing_event: AdSet.BillingEvent.impressions,
    AdSet.Field.optimization_goal: AdSet.OptimizationGoal.reach,
    AdSet.Field.bid_amount: 2,
    AdSet.Field.targeting: {
        Targeting.Field.geo_locations: {
            'countries': ['US'],
        },
    },
})

adset.remote_create(params={
    'status': AdSet.Status.paused,
})
print(adset)
AdSet adSet = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdSet()
  .setName("My Ad Set")
  .setOptimizationGoal(AdSet.EnumOptimizationGoal.VALUE_REACH)
  .setBillingEvent(AdSet.EnumBillingEvent.VALUE_IMPRESSIONS)
  .setBidAmount(2L)
  .setDailyBudget(1000L)
  .setCampaignId(<CAMPAIGN_ID>)
  .setTargeting(
    new Targeting()
      .setFieldGeoLocations(
        new TargetingGeoLocation()
          .setFieldCountries(Arrays.asList("US"))
      )
  )
  .setStatus(AdSet.EnumStatus.VALUE_PAUSED)
  .execute();
String ad_set_id = adSet.getId();
curl \
  -F 'name=My Ad Set' \
  -F 'optimization_goal=REACH' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'bid_amount=2' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<AD_CAMPAIGN_ID>' \
  -F 'targeting={"geo_locations":{"countries":["US"]}}' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adsets

Create an ad set with a lifetime budget

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Targeting;
use FacebookAds\Object\Fields\AdSetFields;
use FacebookAds\Object\Fields\TargetingFields;
use FacebookAds\Object\Values\AdSetBillingEventValues;
use FacebookAds\Object\Values\AdSetOptimizationGoalValues;

$adset = new AdSet(null, 'act_<AD_ACCOUNT_ID>');
$adset->setData(array(
  AdSetFields::NAME => 'LifetimeBudgetSet',
  AdSetFields::LIFETIME_BUDGET => 100000,
  AdSetFields::OPTIMIZATION_GOAL =>
    AdSetOptimizationGoalValues::POST_ENGAGEMENT,
  AdSetFields::BILLING_EVENT => AdSetBillingEventValues::POST_ENGAGEMENT,
  AdSetFields::BID_AMOUNT => 1500,
  AdSetFields::TARGETING => (new Targeting())->setData(array(
    TargetingFields::GEO_LOCATIONS => array(
      'countries' => array('US'),
    ),
  )),
  AdSetFields::CAMPAIGN_ID => <CAMPAIGN_ID>,
  AdSetFields::END_TIME =>
    (new \DateTime("+1 week"))->format(\DateTime::ISO8601),
));

$adset->create(array(
  AdSet::STATUS_PARAM_NAME => AdSet::STATUS_PAUSED,
));
from facebookads.objects import AdSet
  
adset = AdSet(parent_id='act_<AD_ACCOUNT_ID>')
data = {
    AdSet.Field.name: 'LifetimeBudgetSet',
    AdSet.Field.lifetime_budget: 100000,
    AdSet.Field.end_time: 1380610800,
    AdSet.Field.bid_amount: 500,
    AdSet.Field.billing_event: AdSet.BillingEvent.app_installs,
    AdSet.Field.optimization_goal: AdSet.OptimizationGoal.app_installs,
    AdSet.Field.promoted_object: {
        'application_id': <APP_ID>,
        'object_store_url': <APP_STORE_URL>,
    },
    AdSet.Field.targeting: {
        'geo_locations': {
            'countries': ['US'],
        },
    },
    AdSet.Field.status: AdSet.Status.active,
    AdSet.Field.campaign_group_id: <AD_CAMPAIGN_ID>,
    AdSet.Field.redownload: True,
}
adset.remote_create(params=data)
AdSet adSet = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdSet()
  .setName("LifetimeBudgetSet")
  .setLifetimeBudget(100000L)
  .setOptimizationGoal(AdSet.EnumOptimizationGoal.VALUE_POST_ENGAGEMENT)
  .setBillingEvent(AdSet.EnumBillingEvent.VALUE_POST_ENGAGEMENT)
  .setBidAmount(1500L)
  .setTargeting(
    new Targeting()
      .setFieldGeoLocations(
        new TargetingGeoLocation()
          .setFieldCountries(Arrays.asList("US"))
      )
  )
  .setCampaignId(<CAMPAIGN_ID>)
  .setEndTime(end_time)
  .setStatus(AdSet.EnumStatus.VALUE_PAUSED)
  .execute();
String ad_set_id = adSet.getId();
curl \
  -F 'name=LifetimeBudgetSet' \
  -F 'lifetime_budget=100000' \
  -F 'optimization_goal=POST_ENGAGEMENT' \
  -F 'billing_event=POST_ENGAGEMENT' \
  -F 'bid_amount=1500' \
  -F 'targeting={"geo_locations":{"countries":["US"]}}' \
  -F 'campaign_id=<AD_CAMPAIGN_ID>' \
  -F 'end_time=2016-09-08T08:22:38+0000' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adsets

To validate an ad set with a lifetime budget where campaign objective is set to MOBILE_APP_INSTALLS

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Values\BidTypes;

$adset = new AdSet(null, 'act_<AD_ACCOUNT_ID>');
$data = array(
  AdSetFields::NAME => 'LifetimeBudgetSet',
  AdsetFields::LIFETIME_BUDGET => 100000,
  AdSetFields::END_TIME => 1380610800,
  AdSetFields::BID_AMOUNT => 500,
  AdSetFields::BILLING_EVENT => BillingEvents::APP_INSTALLS,
  AdSetFields::OPTIMIZATION_GOAL => OptimizationGoals::APP_INSTALLS,
  AdSetFields::PROMOTED_OBJECT => array(
      'application_id' => <APP_ID>,
      'object_store_url' => <APP_STORE_URL>,
  ),
  AdSetFields::TARGETING => array(
    'geo_locations' => array(
      'countries' => array(
        'US',
      ),
    ),
  ),
  AdSetFields::CAMPAIGN_STATUS => AdSet::STATUS_ACTIVE,
  AdSetFields::CAMPAIGN_GROUP_ID => <AD_CAMPAIGN_ID>,
);
$adset->validate($data);
from facebookads.objects import AdSet

adset = AdSet(parent_id='act_<AD_ACCOUNT_ID>')
data = {
    AdSet.Field.name: 'LifetimeBudgetSet',
    AdSet.Field.lifetime_budget: 100000,
    AdSet.Field.end_time: 1380610800,
    AdSet.Field.bid_amount: 500,
    AdSet.Field.billing_event: AdSet.BillingEvent.app_installs,
    AdSet.Field.optimization_goal: AdSet.OptimizationGoal.app_installs,
    AdSet.Field.promoted_object: {
            'application_id': <APP_ID>,
            'object_store_url': <APP_STORE_URL>,
    },
    AdSet.Field.targeting: {
        'geo_locations': {
            'countries': ['US'],
        },
    },
    AdSet.Field.status: AdSet.Status.active,
    AdSet.Field.campaign_group_id: <AD_CAMPAIGN_ID>,
}
adset.remote_validate(params=data)
curl \
-F "name=LifetimeBudgetSet" \
-F "lifetime_budget=100000" \
-F "end_time=1380610800" \
-F "bid_amount=150" \
-F "billing_event=APP_INSTALLS" \
-F "optimization_goal=APP_INSTALLS" \
-F "promoted_object={'application_id': <APP_ID>, 'object_store_url': <APP_STORE_URL>}" \
-F "targeting={'geo_locations': {'countries': ['US']}}" \
-F "campaign_status=ACTIVE" \
-F "campaign_id=<AD_CAMPAIGN_ID>" \
-F "execution_options=['validate_only']" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adsets"

Considerations

Bid/Budget Validations

There are minimum values of budgets. The validation logic is explained here.

Locale targeted page post If you promote a Page post which has been targeted by locale the ad set targeting must include the same, or a subset of, locale targeting as the Page post.

E.g. if the Page post is targeted at locales 6 (US English) and 24 (UK English), then the ad set must be targeted at one or more of the same locales.

Mobile App Ads Mobile app ad sets should

  • be used in conjunction with targeting spec fields user_device and user_os
  • have a MOBILE_APP_* objective on the campaign

Desktop App Ads Desktop app ad sets must

  • include a targeting spec of either
    • 'page_types':['desktopfeed'] or
    • 'page_types':['rightcolumn'] or
    • 'page_types':['desktop'] along with the other targeting options you have selected.
  • include a CANVAS_APP_* objective

With v2.6 or earlier, you can set page_types in the targeting specs of your ad set. In v2.7, you can only read the page_types, but cannot create or update it; after v2.7 you cannot read it. As of 2.7, you should use new fields, device_platforms, publisher_platforms, and facebook_positions instead. See Targeting Spec

You can make a POST request to adsets edge from the following paths:
When posting to this edge, an AdSet will be created.

Parameters

NameDescription
adlabels
list<Object>

Specifies list of labels to be associated with this object. This field is optional

adset_schedule
list<Object>

Ad set schedule, representing a delivery schedule for a single day

start_minute
int64

A 0 based minute of the day representing when the schedule starts

Required
end_minute
int64

A 0 based minute of the day representing when the schedule ends

Required
days
list<int64>

Array of ints representing which days the schedule is active. Valid values are 0-6 with 0 representing Sunday, 1 representing Monday, ... and 6 representing Saturday.

Required
attribution_window_days
int64

Conversion attribution window, representing days in time of the attribution window length, 1, 7 or 28 days for pixels and 1 day for others. This parameter is only available with the OFFSITE_CONVERSIONS or APP_INSTALLS optimization goal.

bid_amount
integer

Bid amount for this ad set, defined as your true value bid based on optimization_goal. If an ad level bid_amount is specified, updating this value will overwrite the previous ad level bid. Either bid_amount or is_autobid is required except in Reach and Frequency ad sets. The bid amount's unit is cent for currencies like USD, EUR, and the basic unit for currencies like JPY, KRW. The bid amount for ads with IMPRESSION, REACH as billing_event is per 1,000 occurrences, and has to be at least 2 US cents or more; that for ads with other billing_event is for each occurrence, and has a minimum value 1 US cents. The minimum bid amounts of other currencies are of similar value to the US Dollar values provided.

billing_event
enum{APP_INSTALLS, CLICKS, IMPRESSIONS, LINK_CLICKS, OFFER_CLAIMS, PAGE_LIKES, POST_ENGAGEMENT, VIDEO_VIEWS}

The billing event that this adset is using:
APP_INSTALLS: Pay when people install your app.
CLICKS: Deprecated.
IMPRESSIONS: Pay when the ads are shown to people.
LINK_CLICKS: Pay when people click on the link of the ad.
OFFER_CLAIMS: Pay when people claim the offer.
PAGE_LIKES: Pay when people like your page.
POST_ENGAGEMENT: Pay when people engage with your post.
VIDEO_VIEWS: Pay when people watch videos.

campaign_id
numeric string or integer

The ad campaign you wish to add this ad set to.

campaign_spec
Campaign spec

Campaign spec. When the spec is provided, campaign_id field is not required.

creative_sequence
list<numeric string or integer>

Order of the adgroup sequence to be shown to users

daily_budget
int64

The daily budget defined in your account currency, allowed only for ad sets with a duration (difference between end_time and start_time) longer than 24 hours.
Either a daily_budget or a lifetime_budget must be specified.

daily_imps
int64

Daily impressions. Available only for campaigns with buying_type=FIXED_CPM

end_time
datetime

End time, required when lifetime_budget is specified. e.g. 2015-03-12 23:59:59-07:00 or 2015-03-12 23:59:59 PDT. When creating a set with a daily budget, specify end_time=0 to set the set to be ongoing and have no end date. UTC UNIX timestamp

execution_options
list<enum{validate_only, include_recommendations}>
Default value: Set

An execution setting
validate_only: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field.
include_recommendations: this option cannot be used by itself. When this option is used, recommendations for ad object's configuration will be included. A separate section recommendations will be included in the response, but only if recommendations for this specification exist.
If the call passes validation or review, response will be {"success": true}. If the call does not pass, an error will be returned with more details. These options can be used to improve any UI to display errors to the user much sooner, e.g. as soon as a new value is typed into any field corresponding to this ad object, rather than at the upload/save stage, or after review.

frequency_control_specs
list<Object>

An array of frequency control specs for this ad set. As there is only one event type supported currently, this array would have no more than one element. Only available in ad sets of campaigns with BRAND_AWARENESS as objective and REACH as optimization_goal. These cannot be used in Reach & Frequency campaigns.

event
enum{IMPRESSIONS, VIDEO_VIEWS}

Event name, only IMPRESSIONS currently.

Required
interval_days
integer

Interval period in days, between 1 and 90 (inclusive)

Required
max_frequency
integer

The maximum frequency, only 1 is allowed now.

Required
instagram_actor_id
numeric string or integer

The Instagram actor id used for DCO ad on Instagram.

is_autobid
boolean

If autobid is set. Either bid_amount or is_autobid is required except in Reach and Frequency ad sets. Cannot be used when using billing_event=APP_INSTALLS or MOBILE_APP_INSTALLS.

is_average_price_pacing
boolean

Flag used to determine whether average price pacing is enabled. Default value is false.

lifetime_budget
int64

Lifetime budget, defined in your account currency. If specified, you must also specify an end_time.
Either a daily_budget or a lifetime_budget must be specified.

lifetime_imps
int64

Lifetime impressions. Available only for campaigns with buying_type=FIXED_CPM

name
string

Ad set name, max length of 400 characters.

Required
optimization_goal
enum{NONE, APP_INSTALLS, BRAND_AWARENESS, CLICKS, ENGAGED_USERS, EXTERNAL, EVENT_RESPONSES, IMPRESSIONS, LEAD_GENERATION, LINK_CLICKS, OFFER_CLAIMS, OFFSITE_CONVERSIONS, PAGE_ENGAGEMENT, PAGE_LIKES, POST_ENGAGEMENT, REACH, SOCIAL_IMPRESSIONS, VIDEO_VIEWS, APP_DOWNLOADS}

What the ad set is optimizing for.
APP_INSTALLS: Will optimize for people more likely to install your app.
BRAND_AWARENESS: Optimize to reach the most users to spend at least a minimum amount of time on the image or video. You cannot set bid_amount, and is_autobid must be true if this goal is used.
CLICKS: Deprecated
ENGAGED_USER: Will optimize for people more likely to take a particular action in your app
EXTERNAL: FBX only
EVENT_RESPONSES: Will optimize for people more likely to attend your event.
IMPRESSIONS: Will show the ads as many times as possible
LINK_CLICKS: Will optimize for people more likely to click in the link of the ad.
OFFER_CLAIMS: Will optimize for people more likely to claim the offer.
OFFSITE_CONVERSION: Will optimize for people more likely to make a conversion in the site
PAGE_LIKES: Will optimize for people more likely to like your page.
PAGE_ENGAGEMENT: Will optimize for people more likely to engage with your page.
POST_ENGAGEMENT: Will optimize for people more likely toengage with your post.
REACH: Optimize to reach the most unique users of each day or interval specified in frequency_control_specs.
SOCIAL_IMPRESSIONS: Increase the number of impressions with social context.
I.e. with the names of one or more of the user's friends attached to the ad who have already liked the page or installed the app.
VIDEO_VIEWS: Will optimize for people more likely to watch videos.
LEAD_GENERATION: Will optimize for people more likely to fill out a lead generation form.

pacing_type
list<string>

Defines the pacing type, standard by default or using ad scheduling

promoted_object
Object

The object this ad set is promoting across all its ads. Required with certain campaign objectives.
CONVERSIONS

  • pixel_id (Conversion pixel ID)
  • pixel_id (Facebook pixel ID) and custom_event_type
  • pixel_id (Facebook pixel ID) and pixel_rule and custom_event_type
  • event_id (Facebook event ID) and custom_event_type
PAGE_LIKES
page_id
OFFER_CLAIMS
page_id
MOBILE_APP_INSTALLS or MOBILE_APP_ENGAGEMENT
application_id and object_store_url
or application_id, object_store_url, and custom_event_type if the optimization_goal is OFFSITE_CONVERSIONS
CANVAS_APP_INSTALLS or CANVAS_APP_ENGAGEMENT
application_id and object_store_url
PRODUCT_CATALOG_SALES
product_set_id,
or product_set_id and custom_event_type
application_id
int

The ID of a Facebook Application. Usually related to mobile or canvas games being promoted on Facebook for installs or engagement

pixel_id
numeric string or integer

The ID of a Facebook conversion pixel. Used with offsite conversion campaigns.

custom_event_type
enum{COMPLETE_REGISTRATION, CONTENT_VIEW, SEARCH, RATE, TUTORIAL_COMPLETION, ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, LEAD, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, OTHER}

The event from an App Event of a mobile app, or tag of an conversion pixel.

object_store_url
URL

The uri of the mobile / digital store where an application can be bought / downloaded. This is platform specific. When combined with the "application_id" this uniquely specifies an object which can be the subject of a Facebook advertising campaign.

offer_id
numeric string or integer

The ID of an Offer from a Facebook Page.

page_id
int

The ID of a Facebook Page

product_catalog_id
numeric string or integer

The ID of a Product Catalog. Used with Dynamic Product Ads.

product_set_id
numeric string or integer

The ID of a Product Set within a Campaign Group level Product Catalog. Used with Dynamic Product Ads.

event_id
numeric string or integer

The ID of a Facebook Event

redownload
boolean

Allows you to specify that you would like to retrieve all fields of the set in your response. Default value: false.

rf_prediction_id
numeric string or integer

Reach and frequency prediction ID

rtb_flag
boolean

Whether this adset is using RTB or not

start_time
datetime

The start time of the set, e.g. 2015-03-12 23:59:59-07:00 or 2015-03-12 23:59:59 PDT. UTC UNIX timestamp

status
enum{ACTIVE, PAUSED, DELETED, ARCHIVED}

Only ACTIVE and PAUSED are valid for creation. The other statuses can be used for update. If it is set to PAUSED, all its active ads will be paused and have an effective status ADSET_PAUSED.

targeting
Targeting object

An ad set's targeting structure. "countries" is required. See targeting.

time_based_ad_rotation_id_blocks
list<list<int64>>

Specify ad creative that displays at custom date ranges in a campaign as an array. A list of Adgroup IDs. The list of ads to display for each time range in a given schedule. For example display first ad in Adgroup for first date range, second ad for second date range, and so on. You can display more than one ad per date range by providing more than one ad group ID per array. For example set time_based_ad_rotation_id_blocks to [[1], [2, 3], [1, 4]]. On the first date range show ad 1, on the second date range show ad 2 and ad 3 and on the last date range show ad 1 and ad 4. Use with time_based_ad_rotation_intervals to specify date ranges.

time_based_ad_rotation_intervals
list<int64>

Date range when specific ad creative displays during a campaign. Provide date ranges in an array of UNIX timestamps where each timestamp represents the start time for each date range. For example a 3-day campaign from May 9 12am to May 11 11:59PM PST can have three date ranges, the first date range starts from May 9 12:00AM to May 9 11:59PM, second date range starts from May 10 12:00AM to May 10 11:59PM and last starts from May 11 12:00AM to May 11 11:59PM. The first timestamp should match the campaign start time. The last timestamp should be at least 1 hour before the campaign end time. You must provide at least two date ranges. All date ranges must cover the whole campaign length, so any date range cannot exceed campaign length. Use with time_based_ad_rotation_id_blocks to specify ad creative for each date range.

Return Type

Struct {
id: numeric string,
success: bool,
}
You may perform a POST request to the following edge from this node:

Validation Rules

ErrorDescription
100Invalid parameter
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
2626The request for a reach frequency campaign has failed.
294Managing advertisements requires an access token with the extended permission for ads_management
384The video you tried to upload is too long. Please try again with a shorter video.
192Invalid phone number
2625The request for a reach frequency campaign is invalid.
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API
331Your picture is too tall or too wide. Try to pick something closer to a square.

Updating

Examples

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;

$adset = new AdSet('<AD_SET_ID>');
$adset->name = 'New AdSet Name';
$adset->update();
from facebookads.objects import AdSet

adset = AdSet('<AD_SET_ID>')
adset[AdSet.Field.name] = 'New AdSet Name'
adset.remote_update()
curl \
-F "name=New AdSet Name" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_SET_ID>"

To update the end_time of an ad set <AD_SET_ID>, using ISO-8601 date-time format

use FacebookAds\Object\AdSet;

$adset = new AdSet('<AD_SET_ID>');
$adset->end_time = '2013-10-02T00:00:00-0700';
$adset->update();
from facebookads.objects import AdSet

adset = AdSet('<AD_SET_ID>')
adset[AdSet.Field.end_time] = '2013-10-02T00:00:00-0700'
adset.remote_update()
curl \
-F "end_time=2013-10-02T00:00:00-0700" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_SET_ID>"

To update the status of an ad set <AD_SET_ID> to paused

use FacebookAds\Object\AdSet;

$adset = new AdSet('<AD_SET_ID>');
$adset->campaign_status = AdSet::STATUS_PAUSED;
$adset->update();
from facebookads.objects import AdSet

adset = AdSet('<AD_SET_ID>')
adset[AdSet.Field.status] = AdSet.Status.paused
adset.remote_update()
curl \
-F "campaign_status=PAUSED" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_SET_ID>"

Remarks

An archived ad set can only update two fields: name and campaign_status. The campaign_status field can only be changed to DELETED.

A deleted ad set can only change its name.

There are some considerations to take into account when adjusting an ad set's budget value:

  • When updating a set's lifetime or daily budget to a lower value, the new value must be at least 10% greater than the current amount spent already. For example: if an ad set has a $1000 lifetime budget and has spend $300 so far, the lowest new lifetime budget would be $330.
  • If you've already spent more than your new budget at the time you update it, your ads will stop running until the next budget cycle.
  • Since v2.4, ad sets have a minimum required budget. Any update must take that into consideration. Check the details at the Create Considerations section from this page.

The budget type of an ad set cannot be changed after the ad set it created. I.e. you cannot switch from a daily budget to a lifetime budget, and vice versa.

You can update an AdSet by making a POST request to /{graph_ad_campaign_node_id}.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
  • business_management
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
account_id
numeric string

Ad Account ID

adlabels
list<Object>

Specifies list of labels to be associated with this object. This field is optional

adset_schedule
list<Object>

Ad set schedule, representing a delivery schedule for a single day

start_minute
int64

A 0 based minute of the day representing when the schedule starts

Required
end_minute
int64

A 0 based minute of the day representing when the schedule ends

Required
days
list<int64>

Array of ints representing which days the schedule is active. Valid values are 0-6 with 0 representing Sunday, 1 representing Monday, ... and 6 representing Saturday.

Required
attribution_window_days
int64

Conversion attribution window, representing days in time of the attribution window length, 1, 7 or 28 days for pixels and 1 day for others. This parameter is only available with the OFFSITE_CONVERSIONS or APP_INSTALLS optimization goal.

bid_amount
integer

Bid amount for this ad set, defined as your true value bid based on optimization_goal. If an ad level bid_amount is specified, updating this value will overwrite the previous ad level bid. Either bid_amount or is_autobid is required except in Reach and Frequency ad sets. The bid amount's unit is cent for currencies like USD, EUR, and the basic unit for currencies like JPY, KRW. The bid amount for ads with IMPRESSION, REACH as billing_event is per 1,000 occurrences, and has to be at least 2 US cents or more; that for ads with other billing_event is for each occurrence, and has a minimum value 1 US cents. The minimum bid amounts of other currencies are of similar value to the US Dollar values provided.

billing_event
enum{APP_INSTALLS, CLICKS, IMPRESSIONS, LINK_CLICKS, OFFER_CLAIMS, PAGE_LIKES, POST_ENGAGEMENT, VIDEO_VIEWS}

The billing event that this adset is using:
APP_INSTALLS: Pay when people install your app.
CLICKS: Deprecated.
IMPRESSIONS: Pay when the ads are shown to people.
LINK_CLICKS: Pay when people click on the link of the ad.
OFFER_CLAIMS: Pay when people claim the offer.
PAGE_LIKES: Pay when people like your page.
POST_ENGAGEMENT: Pay when people engage with your post.
VIDEO_VIEWS: Pay when people watch videos.

creative_sequence
list<numeric string or integer>

Order of the adgroup sequence to be shown to users

daily_budget
int64

The daily budget defined in your account currency, allowed only for ad sets with a duration (difference between end_time and start_time) longer than 24 hours.
Either a daily_budget or a lifetime_budget must be specified.

daily_imps
int64

Daily impressions. Available only for campaigns with buying_type=FIXED_CPM

end_time
datetime

End time, required when lifetime_budget is specified. e.g. 2015-03-12 23:59:59-07:00 or 2015-03-12 23:59:59 PDT. When creating a set with a daily budget, specify end_time=0 to set the set to be ongoing and have no end date. UTC UNIX timestamp

execution_options
list<enum{validate_only, include_recommendations}>
Default value: Set

An execution setting
validate_only: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field.
include_recommendations: this option cannot be used by itself. When this option is used, recommendations for ad object's configuration will be included. A separate section recommendations will be included in the response, but only if recommendations for this specification exist.
If the call passes validation or review, response will be {"success": true}. If the call does not pass, an error will be returned with more details. These options can be used to improve any UI to display errors to the user much sooner, e.g. as soon as a new value is typed into any field corresponding to this ad object, rather than at the upload/save stage, or after review.

is_autobid
boolean

If autobid is set. Either bid_amount or is_autobid is required except in Reach and Frequency ad sets. Cannot be used when using billing_event=APP_INSTALLS or MOBILE_APP_INSTALLS.

is_average_price_pacing
boolean

Flag used to determine whether average price pacing is enabled. Default value is false.

lifetime_budget
int64

Lifetime budget, defined in your account currency. If specified, you must also specify an end_time.
Either a daily_budget or a lifetime_budget must be specified.

lifetime_imps
int64

Lifetime impressions. Available only for campaigns with buying_type=FIXED_CPM

name
string

Ad set name, max length of 400 characters.

optimization_goal
enum{NONE, APP_INSTALLS, BRAND_AWARENESS, CLICKS, ENGAGED_USERS, EXTERNAL, EVENT_RESPONSES, IMPRESSIONS, LEAD_GENERATION, LINK_CLICKS, OFFER_CLAIMS, OFFSITE_CONVERSIONS, PAGE_ENGAGEMENT, PAGE_LIKES, POST_ENGAGEMENT, REACH, SOCIAL_IMPRESSIONS, VIDEO_VIEWS, APP_DOWNLOADS}

What the ad set is optimizing for.
APP_INSTALLS: Will optimize for people more likely to install your app.
BRAND_AWARENESS: Optimize to reach the most users to spend at least a minimum amount of time on the image or video. You cannot set bid_amount, and is_autobid must be true if this goal is used.
CLICKS: Deprecated
ENGAGED_USER: Will optimize for people more likely to take a particular action in your app
EXTERNAL: FBX only
EVENT_RESPONSES: Will optimize for people more likely to attend your event.
IMPRESSIONS: Will show the ads as many times as possible
LINK_CLICKS: Will optimize for people more likely to click in the link of the ad.
OFFER_CLAIMS: Will optimize for people more likely to claim the offer.
OFFSITE_CONVERSION: Will optimize for people more likely to make a conversion in the site
PAGE_LIKES: Will optimize for people more likely to like your page.
PAGE_ENGAGEMENT: Will optimize for people more likely to engage with your page.
POST_ENGAGEMENT: Will optimize for people more likely toengage with your post.
REACH: Optimize to reach the most unique users of each day or interval specified in frequency_control_specs.
SOCIAL_IMPRESSIONS: Increase the number of impressions with social context.
I.e. with the names of one or more of the user's friends attached to the ad who have already liked the page or installed the app.
VIDEO_VIEWS: Will optimize for people more likely to watch videos.
LEAD_GENERATION: Will optimize for people more likely to fill out a lead generation form.

pacing_type
list<string>

Defines the pacing type, standard by default or using ad scheduling

promoted_object
Object

The object this ad set is promoting across all its ads. Required with certain campaign objectives.
CONVERSIONS

  • pixel_id (Conversion pixel ID)
  • pixel_id (Facebook pixel ID) and custom_event_type
  • pixel_id (Facebook pixel ID) and pixel_rule and custom_event_type
  • event_id (Facebook event ID) and custom_event_type
PAGE_LIKES
page_id
OFFER_CLAIMS
page_id
MOBILE_APP_INSTALLS or MOBILE_APP_ENGAGEMENT
application_id and object_store_url
or application_id, object_store_url, and custom_event_type if the optimization_goal is OFFSITE_CONVERSIONS
CANVAS_APP_INSTALLS or CANVAS_APP_ENGAGEMENT
application_id and object_store_url
PRODUCT_CATALOG_SALES
product_set_id,
or product_set_id and custom_event_type
application_id
int

The ID of a Facebook Application. Usually related to mobile or canvas games being promoted on Facebook for installs or engagement

pixel_id
numeric string or integer

The ID of a Facebook conversion pixel. Used with offsite conversion campaigns.

custom_event_type
enum{COMPLETE_REGISTRATION, CONTENT_VIEW, SEARCH, RATE, TUTORIAL_COMPLETION, ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, LEAD, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, OTHER}

The event from an App Event of a mobile app, or tag of an conversion pixel.

object_store_url
URL

The uri of the mobile / digital store where an application can be bought / downloaded. This is platform specific. When combined with the "application_id" this uniquely specifies an object which can be the subject of a Facebook advertising campaign.

offer_id
numeric string or integer

The ID of an Offer from a Facebook Page.

page_id
int

The ID of a Facebook Page

product_catalog_id
numeric string or integer

The ID of a Product Catalog. Used with Dynamic Product Ads.

product_set_id
numeric string or integer

The ID of a Product Set within a Campaign Group level Product Catalog. Used with Dynamic Product Ads.

event_id
numeric string or integer

The ID of a Facebook Event

redownload
boolean

Allows you to specify that you would like to retrieve all fields of the set in your response. Default value: false.

rf_prediction_id
numeric string or integer

Reach and frequency prediction ID

start_time
datetime

The start time of the set, e.g. 2015-03-12 23:59:59-07:00 or 2015-03-12 23:59:59 PDT. UTC UNIX timestamp

status
enum{ACTIVE, PAUSED, DELETED, ARCHIVED}

Only ACTIVE and PAUSED are valid for creation. The other statuses can be used for update. If it is set to PAUSED, all its active ads will be paused and have an effective status ADSET_PAUSED.

targeting
Targeting object

An ad set's targeting structure. "countries" is required. See targeting.

time_based_ad_rotation_id_blocks
list<list<int64>>

Specify ad creative that displays at custom date ranges in a campaign as an array. A list of Adgroup IDs. The list of ads to display for each time range in a given schedule. For example display first ad in Adgroup for first date range, second ad for second date range, and so on. You can display more than one ad per date range by providing more than one ad group ID per array. For example set time_based_ad_rotation_id_blocks to [[1], [2, 3], [1, 4]]. On the first date range show ad 1, on the second date range show ad 2 and ad 3 and on the last date range show ad 1 and ad 4. Use with time_based_ad_rotation_intervals to specify date ranges.

time_based_ad_rotation_intervals
list<int64>

Date range when specific ad creative displays during a campaign. Provide date ranges in an array of UNIX timestamps where each timestamp represents the start time for each date range. For example a 3-day campaign from May 9 12am to May 11 11:59PM PST can have three date ranges, the first date range starts from May 9 12:00AM to May 9 11:59PM, second date range starts from May 10 12:00AM to May 10 11:59PM and last starts from May 11 12:00AM to May 11 11:59PM. The first timestamp should match the campaign start time. The last timestamp should be at least 1 hour before the campaign end time. You must provide at least two date ranges. All date ranges must cover the whole campaign length, so any date range cannot exceed campaign length. Use with time_based_ad_rotation_id_blocks to specify ad creative for each date range.

Return Type

Struct {
success: bool,
}
You may perform a POST request to the following edge from this node:

Validation Rules

ErrorDescription
100Invalid parameter
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
2626The request for a reach frequency campaign has failed.
294Managing advertisements requires an access token with the extended permission for ads_management
384The video you tried to upload is too long. Please try again with a shorter video.
192Invalid phone number
2625The request for a reach frequency campaign is invalid.
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API
331Your picture is too tall or too wide. Try to pick something closer to a square.

Deleting

Examples

use FacebookAds\Object\AdSet;

$adset = new AdSet($adset_id);
$adset->delete();
from facebookads.objects import AdSet

adset = AdSet('<AD_SET_ID>')
adset.remote_delete()
curl \
-F "campaign_status=DELETED" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_SET_ID>"
You can delete an AdSet by making a DELETE request to /{graph_ad_campaign_node_id}.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}
You may perform a DELETE request to the following edge from this node:

Validation Rules

ErrorDescription
100Invalid parameter