Graph API Version

Ad Set

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. See Optimized CPM and Promoted Object.

For example, 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=<CAMPAIGN_ID>' \
  -F 'targeting={"geo_locations":{"countries":["US"]}}' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adsets

Create an ad set with a lifetime budget

curl \
  -F 'name=LifetimeBudgetSet' \
  -F 'lifetime_budget=100000' \
  -F 'optimization_goal=POST_ENGAGEMENT' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'bid_amount=1500' \
  -F 'targeting={"geo_locations":{"countries":["US"]}}' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'end_time=2017-09-21T15:41:30+0000' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/VERSION/act_<AD_ACCOUNT_ID>/adsets

Limits

The following are the limits on ad sets

Limit Value

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-archived ads

Housing, Employment and Credit Ads

Facebook is committed to protecting people from discrimination, and we are continually improving our ability to detect and deter potential abuse. It’s already against our policies to discriminate by wrongfully targeting or excluding specific groups of people. As part of a historic settlement agreement, we are making changes to the way we manage housing, employment and credit ads.

Advertisers must specify a special_ad_category for ad campaigns that market housing, employment, and credit. In doing so, the set of targeting options available for ads in these campaigns will be restricted. See Special Ad Category for more information.

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.

Examples

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

$adset = new AdSet(<AD_SET_ID>);
$adset->read(array(
  AdSetFields::NAME,
  AdSetFields::CONFIGURED_STATUS,
  AdSetFields::EFFECTIVE_STATUS,
));

echo $adset->{AdSetFields::NAME}.PHP_EOL;
echo $adset->{AdSetFields::CONFIGURED_STATUS}.PHP_EOL;
echo $adset->{AdSetFields::EFFECTIVE_STATUS}.PHP_EOL;
from facebookads.adobjects.adset import AdSet

adset = AdSet(fbid=<AD_SET_ID>)
fields = [
    AdSet.Field.name,
    AdSet.Field.configured_status,
    AdSet.Field.effective_status,
]
adset.remote_read(fields=fields)
print(adset[AdSet.Field.name])
print(adset[AdSet.Field.configured_status])
print(adset[AdSet.Field.effective_status])
AdSet adSet2 = new AdSet(<AD_SET_ID>, context).get()
  .requestNameField()
  .requestConfiguredStatusField()
  .requestEffectiveStatusField()
  .execute();
curl -G \
  -d 'fields=name,configured_status,effective_status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<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>);
$params = array(
  'date_format' => 'U',
);
$adset->read(array(
  AdSetFields::START_TIME,
  AdSetFields::END_TIME,
  AdSetFields::CONFIGURED_STATUS,
  AdSetFields::EFFECTIVE_STATUS,
  AdSetFields::CAMPAIGN_ID,
), $params);

echo $adset->{AdSetFields::EFFECTIVE_STATUS}.PHP_EOL;
from facebookads.adobjects.adset import AdSet

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

print(adset[AdSet.Field.effective_status])
AdSet adSet2 = new AdSet(<AD_SET_ID>, context).get()
  .setParam("date_format", "U")
  .requestStartTimeField()
  .requestEndTimeField()
  .requestConfiguredStatusField()
  .requestEffectiveStatusField()
  .requestCampaignIdField()
  .execute();
curl -G \
  -d 'date_format=U' \
  -d 'fields=start_time,end_time,configured_status,effective_status,campaign_id' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_SET_ID>

To retrieve information for multiple ad sets:

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

$ad_set_ids = array(<AD_SET_1_ID>, <AD_SET_2_ID>, <AD_SET_3_ID>);
$fields = array(
  AdSetFields::NAME,
  AdSetFields::CONFIGURED_STATUS,
  AdSetFields::EFFECTIVE_STATUS,
);
$adsets = AdSet::readIds($ad_set_ids, $fields);

foreach ($adsets as $adset) {
  echo $adset->{AdSetFields::NAME}.PHP_EOL;
}
curl -G \
  -d 'fields=name,configured_status,effective_status' \
  -d 'ids=1000002,1000002,1000002' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/

To read all ad sets from one ad account:

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

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

foreach ($adsets as $adset) {
  echo $adset->{AdSetFields::NAME}.PHP_EOL;
}
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.adset import AdSet

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

for adset in adsets:
    print(adset[AdSet.Field.name])
APINodeList<AdSet> adSets = new AdAccount(act_<AD_ACCOUNT_ID>, context).getAdSets()
  .requestNameField()
  .requestConfiguredStatusField()
  .requestEffectiveStatusField()
  .execute();
curl -G \
  -d 'fields=name,configured_status,effective_status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adsets

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

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

$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$adsets = $account->getAdSets(
  array(),
  array(
    AdSetFields::EFFECTIVE_STATUS => array(
      AdSet::STATUS_PAUSED,
    ),
  ));

foreach ($adsets as $adset) {
  echo $adset->{AdSetFields::NAME}.PHP_EOL;
}
APINodeList<AdSet> adSets = new AdAccount(act_<AD_ACCOUNT_ID>, context).getAdSets()
  .setEffectiveStatus("[\"PAUSED\"]")
  .execute();
curl -G \
  -d 'effective_status=["PAUSED"]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adsets

To read the end_time of multiple ad sets.

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

$adsets = AdSet::readIds(
  array($ad_set_1_id, $ad_set_2_id),
  array(AdSetFields::END_TIME));

foreach ($adsets as $adset) {
  echo $adset->{AdSetFields::END_TIME}.PHP_EOL;
}
curl -G \
  -d 'fields=end_time' \
  -d 'ids=1000002,1000002' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/

Example

Graph API Explorer
GET /v5.0/<AD_SET_ID>/?fields=adset_schedule HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/<AD_SET_ID>/',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/<AD_SET_ID>/",
    {
        "fields": "adset_schedule"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("fields", "adset_schedule");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/<AD_SET_ID>/",
    params,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"fields": @"adset_schedule",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/<AD_SET_ID>/"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl -X GET \
  -d 'fields="adset_schedule"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v5.0/<AD_SET_ID>/
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

ParameterDescription
date_preset
enum{today, yesterday, this_month, last_month, this_quarter, lifetime, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year}

Date Preset

time_range
{'since':YYYY-MM-DD,'until':YYYY-MM-DD}

Time Range

since
datetime

A date in the format of "YYYY-MM-DD", which means from the beginning midnight of that day.

until
datetime

A date in the format of "YYYY-MM-DD", which means to the beginning midnight of the following day.

Fields

FieldDescription
id
numeric string

ID for the Ad Set

account_id
numeric string

ID for the Ad Account associated with this Ad Set

adlabels

Ad Labels associated with this ad set

adset_schedule

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

asset_feed_id
numeric string

The ID of the asset feed that constains a content to create ads

attribution_spec
list<AttributionSpec>

Conversion attribution spec used for attributing conversions for optimization. Supported window lengths differ by optimization goal and campaign objective. See Validation, Attribution Spec.

bid_adjustments
AdBidAdjustments

Map of bid adjustment types to values

bid_amount
unsigned int32

Bid cap or target cost for this ad set. The bid cap used in a lowest cost bid strategy is defined as the maximum bid you want to pay for a result based on your optimization_goal. The target cost used in a target cost bid strategy lets Facebook bid on your behalf to meet your target on average and keep costs stable as you raise budget.

The bid amount's unit is cents for currencies like USD, EUR, and the basic unit for currencies like JPY, KRW. The bid amount for ads with IMPRESSION or REACH as billing_event is per 1,000 occurrences of that event, and the bid amount for ads with other billing_events is for each occurrence.

bid_constraints
AdCampaignBidConstraint

Choose bid constraints for ad set to suit your specific business goals. It usually works together with bid_strategy field.

bid_info
map<string, unsigned int32>

Map of bid objective to bid value.

bid_strategy
enum {LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, TARGET_COST}

Bid strategy for this ad set when you use AUCTION as your buying type:
LOWEST_COST_WITHOUT_CAP: Designed to get the most results for your budget based on your ad set optimization_goal without limiting your bid amount. This is the best strategy if you care most about cost efficiency. However with this strategy it may be harder to get stable average costs as you spend. This strategy is also known as automatic bidding. Learn more in Ads Help Center, About bid strategies: Lowest cost.
LOWEST_COST_WITH_BID_CAP: Designed to get the most results for your budget based on your ad set optimization_goal while limiting actual bid to your specified amount. With a bid cap you have more control over your cost per actual optimization event. However if you set a limit which is too low you may get less ads delivery. Get your bid cap with the field bid_amount. This strategy is also known as manual maximum-cost bidding. Learn more in Ads Help Center, About bid strategies: Lowest cost.
TARGET_COST: Maintains a stable average cost while delivering towards your optimization_goal as you raise your budget. We recommend this strategy if you care most about maintaining stable average costs for your ads. However, note that this may be less cost-efficient than the lowest cost strategy. Get your target average cost in the bid_amount field. Target cost bid strategy is also known as manual average-cost bidding. Learn more in Ads Help Center, About bid strategies: Target cost.
Note: If you enable campaign budget optimization, you should get bid_strategy at the parent campaign level.

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

The billing event for this ad set:
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 your video ads for at least 10 seconds.
THRUPLAY: Pay for ads that are played to completion, or played for at least 15 seconds.

budget_remaining
numeric string

Remaining budget of this Ad Set

campaign

The campaign that contains this ad set

campaign_id
numeric string

The ID of the campaign that contains this ad set

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

Time when this Ad Set was created

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.

daily_min_spend_target
numeric string

Daily minimum spend target of the ad set defined in your account currency. To use this field, daily budget must be specified in the Campaign. This target is not a guarantee but our best effort.

daily_spend_cap
numeric string

Daily spend cap of the ad set defined in your account currency. To use this field, daily budget must be specified in the Campaign.

destination_type
string

Destination of ads in this Ad Set. For example: Website, App and Messenger.

effective_status
enum {ACTIVE, PAUSED, DELETED, CAMPAIGN_PAUSED, ARCHIVED, IN_PROCESS, WITH_ISSUES}

The effective status of the adset. The status could be effective either because of its own status, or the status of its parent campaign. WITH_ISSUES is available for version 3.2 or higher. IN_PROCESS is available for version 4.0 or higher.

end_time
datetime

End time, in UTC UNIX timestamp

frequency_control_specs

An array of frequency control specs for this ad set. As there is only one event type currently supported, this array has no more than one element. Writes to this field are only available in ad sets where REACH is the objective.

full_funnel_exploration_mode
enum

Exploration mode for full funnel optimization. For example: limited exploration and extended exploration.

instagram_actor_id
numeric string

Represents your Instagram account id, used for ads, including dynamic creative ads on Instagram.

is_dynamic_creative
bool

Whether this ad set is a dynamic creative ad set. dynamic creative ad can be created only under ad set with this field set to be true.

issues_info

Issues for this ad set that prevented it from deliverying

lifetime_budget
numeric string

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

lifetime_imps
int32

Lifetime impressions. Available only for campaigns with buying_type=FIXED_CPM

lifetime_min_spend_target
numeric string

Lifetime minimum spend target of the ad set defined in your account currency. To use this field, lifetime budget must be specified in the Campaign. This target is not a guarantee but our best effort.

lifetime_spend_cap
numeric string

Lifetime spend cap of the ad set defined in your account currency. To use this field, lifetime budget must be specified in the Campaign.

name
string

Name of the ad set

optimization_goal
enum {NONE, APP_INSTALLS, BRAND_AWARENESS, AD_RECALL_LIFT, CLICKS, ENGAGED_USERS, EVENT_RESPONSES, IMPRESSIONS, LEAD_GENERATION, LINK_CLICKS, OFFER_CLAIMS, OFFSITE_CONVERSIONS, PAGE_ENGAGEMENT, PAGE_LIKES, POST_ENGAGEMENT, REACH, SOCIAL_IMPRESSIONS, VIDEO_VIEWS, APP_DOWNLOADS, TWO_SECOND_CONTINUOUS_VIDEO_VIEWS, LANDING_PAGE_VIEWS, VALUE, THRUPLAY, REPLIES, DERIVED_EVENTS}

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.
AD_RECALL_LIFT: Optimize for people more likely to remember seeing your ads.
CLICKS: Deprecated. Only available in read mode.
ENGAGED_USERS: Optimize for people more likely to take a particular action in your app.
EVENT_RESPONSES: Optimize for people more likely to attend your event.
IMPRESSIONS: Show the ads as many times as possible.
LEAD_GENERATION: Optimize for people more likely to fill out a lead generation form.
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_CONVERSIONS: Optimize for people more likely to make a conversion in the site
PAGE_ENGAGEMENT: Optimize for people more likely to engage with your page.
PAGE_LIKES: Optimize for people more likely to like 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 delivery of your ads to people who are more likely to watch videos for at least 10 seconds.
VALUE: Optimize for maximum total purchase value within the specified attribution window.
THRUPLAY: Optimize delivery of your ads to people who are more likely to play your ad to completion, or play it for at least 15 seconds.
REPLIES: Directs ads to people more likely to have a conversation with the business.
DERIVED_EVENTS: Optimize for retention, which reaches people who are most likely to return to the app and open it again during a given time frame after installing. You can choose either two days, meaning the app is likely to be reopened between 24 and 48 hours after installation; or seven days, meaning the app is likely to be reopened between 144 and 168 hours after installation.

optimization_sub_event
string

Optimization sub event for a specific optimization goal. For example: Sound-On event for Video-View-2s optimization goal.

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.

review_feedback
string

Reviews for dynamic creative ad

rf_prediction_id
id

Reach and frequency prediction ID

source_adset

The source ad set that this ad set was copied from

source_adset_id
numeric string

The source ad set id that this ad set was copied from

start_time
datetime

Start time, in UTC UNIX timestamp

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. The field returns the same value as configured_status, and is the suggested one to use.

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

Time when the Ad Set was updated

use_new_app_click
bool

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

Edges

EdgeDescription

The activities of this ad set

The ad studies containing this ad set

The creatives of this ad set

Ad rules that govern this ad set - by default, this only returns rules that either directly mention the ad set by id or indirectly through the set entity_type

The ads under this ad set

Async ad requests for this ad set

The copies of this ad set

The delivery estimate for this ad set

The targeting description sentence for this ad set

Validation Rules

ErrorDescription
100Invalid parameter
80004There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
200Permissions error

Creating

Examples

Validate an ad set with a daily budget where campaign objective is set to APP_INSTALLS

curl -X POST \ -F 'name="Mobile App Installs Ad Set"' \ -F 'daily_budget=1000' \ -F 'bid_amount=2' \ -F 'billing_event="IMPRESSIONS"' \ -F 'optimization_goal="APP_INSTALLS"' \ -F 'campaign_id="<AD_CAMPAIGN_ID>"' \ -F 'promoted_object={ "application_id": "<APP_ID>", "object_store_url": "<APP_STORE_URL>" }' \ -F 'targeting={ "device_platforms": [ "mobile" ], "facebook_positions": [ "feed" ], "geo_locations": { "countries": [ "US" ] }, "publisher_platforms": [ "facebook", "audience_network" ], "user_os": [ "IOS" ] }' \ -F 'status="PAUSED"' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v5.0/act_<AD_ACCOUNT_ID>/adsets
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const AdAccount = bizSdk.AdAccount; const AdSet = bizSdk.AdSet; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<AD_ACCOUNT_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'Mobile App Installs Ad Set', 'daily_budget' : '1000', 'bid_amount' : '2', 'billing_event' : 'IMPRESSIONS', 'optimization_goal' : 'APP_INSTALLS', 'campaign_id' : '<adCampaignAppInstallsID>', 'promoted_object' : {'application_id':'<appID>','object_store_url':'<appLink>'}, 'targeting' : {'device_platforms':['mobile'],'facebook_positions':['feed'],'geo_locations':{'countries':['US']},'publisher_platforms':['facebook','audience_network'],'user_os':['IOS']}, 'status' : 'PAUSED', }; const adsets = (new AdAccount(id)).createAdSet( fields, params ); logApiCallResult('adsets api call complete.', adsets);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\AdSet; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<AD_ACCOUNT_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'Mobile App Installs Ad Set', 'daily_budget' => '1000', 'bid_amount' => '2', 'billing_event' => 'IMPRESSIONS', 'optimization_goal' => 'APP_INSTALLS', 'campaign_id' => '<adCampaignAppInstallsID>', 'promoted_object' => array('application_id' => '<appID>','object_store_url' => '<appLink>'), 'targeting' => array('device_platforms' => array('mobile'),'facebook_positions' => array('feed'),'geo_locations' => array('countries' => array('US')),'publisher_platforms' => array('facebook','audience_network'),'user_os' => array('IOS')), 'status' => 'PAUSED', ); echo json_encode((new AdAccount($id))->createAdSet( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount from facebook_business.adobjects.adset import AdSet from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'Mobile App Installs Ad Set', 'daily_budget': '1000', 'bid_amount': '2', 'billing_event': 'IMPRESSIONS', 'optimization_goal': 'APP_INSTALLS', 'campaign_id': '<adCampaignAppInstallsID>', 'promoted_object': {'application_id':'<appID>','object_store_url':'<appLink>'}, 'targeting': {'device_platforms':['mobile'],'facebook_positions':['feed'],'geo_locations':{'countries':['US']},'publisher_platforms':['facebook','audience_network'],'user_os':['IOS']}, 'status': 'PAUSED', } print AdAccount(id).create_ad_set( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<AD_ACCOUNT_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createAdSet() .setName(\"Mobile App Installs Ad Set\") .setDailyBudget(1000L) .setBidAmount(2L) .setBillingEvent(AdSet.EnumBillingEvent.VALUE_IMPRESSIONS) .setOptimizationGoal(AdSet.EnumOptimizationGoal.VALUE_APP_INSTALLS) .setCampaignId(\"<adCampaignAppInstallsID>\") .setPromotedObject(\"{\\"application_id\\":\\"<appID>\\",\\"object_store_url\\":\\"<appLink>\\"}\") .setTargeting( new Targeting() .setFieldDevicePlatforms(Arrays.asList(Targeting.EnumDevicePlatforms.VALUE_MOBILE)) .setFieldFacebookPositions(Arrays.asList(\"feed\")) .setFieldGeoLocations( new TargetingGeoLocation() .setFieldCountries(Arrays.asList(\"US\")) ) .setFieldPublisherPlatforms(Arrays.asList(\"facebook\", \"audience_network\")) .setFieldUserOs(Arrays.asList(\"IOS\")) ) .setStatus(AdSet.EnumStatus.VALUE_PAUSED) .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) adsets = ad_account.adsets.create({ name: 'Mobile App Installs Ad Set', daily_budget: '1000', bid_amount: '2', billing_event: 'IMPRESSIONS', optimization_goal: 'APP_INSTALLS', campaign_id: '<adCampaignAppInstallsID>', promoted_object: {'application_id':'<appID>','object_store_url':'<appLink>'}, targeting: {'device_platforms':['mobile'],'facebook_positions':['feed'],'geo_locations':{'countries':['US']},'publisher_platforms':['facebook','audience_network'],'user_os':['IOS']}, status: 'PAUSED', })

Considerations

Bid/Budget Validations

When creating an ad set, from v2.4 and on, there will be a minimum budget for different billing events (clicks, impressions, actions). Minimum values are defined in terms of the daily budget but apply to lifetime budgets as well. For example, if the minimum daily budget is $5, a campaign lasting 5 days will need at least $25 for budget. All values in this section are in US Dollars. Differenct currency has different minimum daily budget limit.

If bid_strategy is set to LOWEST_COST_WITHOUT_CAP in the ad set:

Billing Event Minimum Daily Budget Notes

Impressions

$0.50

Clicks/Likes/Video Views

$2.50

Low-frequency Actions

$40

Low-frequency actions include mobile app installs, offer claims or canvas app installs. Important: This minimum daily budget is the same for all countries.

If bid_strategy is set to LOWEST_COST_WITH_BID_CAP in the ad set:

Billing Event Minimum Daily Budget

Impressions

At least the bid_amount. For example, if the bid amount is $10, then $10 will be the minimum budget required.

Clicks/Actions

5x the bid_amount for a Click or Action. For example, if the bid amount is $5 per click/action, then $25 will be the minimum budget required.

Budgets in other non-USD currencies will be converted and validated upon time of ad set creation.

For ads belonging to ad accounts from countries in the list below, the minimum values are 2x the ones in the tables. For example if billing event is an impression, minimum daily budget is $0.50 but in the the following countries minimum would be $1.00:

Australia, Austria, Belgium, Canada, Denmark, Finland, France, Germany, Greece, Hong Kong, Israel, Italy, Japan, Netherlands, New Zealand, Norway, Singapore, South Korea, Spain, Sweden, Switzerland, Taiwan, United Kingdom, United States of America.

The only exception to this rule are low-frequency actions when bid_strategy is LOWEST_COST_WITHOUT_CAP.

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
You can make a POST request to copies edge from the following paths:
When posting to this edge, an AdSet will be created.

Parameters

ParameterDescription
campaign_id
numeric string or integer

Single ID of a campaign to make parent of the copy. The copy inherits all campaign settings, such as budget from the parent.Ignore if you want to keep the copy under the original campaign parent.

deep_copy
boolean
Default value: false

Whether to copy all the child ads. Limits: the total number of children ads to copy should not exceed 3 for a synchronous call and 51 for an asynchronous call.

end_time
datetime

The end 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. When creating a set with a daily budget, specify end_time=0 to set the set to be ongoing without end date. If not set, the copied adset will inherit the end time from the original set

rename_options
JSON or object-like arrays

Rename options

rename_strategy
enum {DEEP_RENAME, ONLY_TOP_LEVEL_RENAME, NO_RENAME}
Default value: ONLY_TOP_LEVEL_RENAME

DEEP_RENAME: will change this object's name and children's names in the copied object. ONLY_TOP_LEVEL_RENAME: will change the this object's name but won't change the children's name in the copied object. NO_RENAME: will change no name in the copied object

rename_prefix
string

A prefix to copy names. Defaults to null if not provided.

rename_suffix
string

A suffix to copy names. Defaults to null if not provided and appends a localized string of - Copy based on the ad account locale.

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. If not set, the copied adset will inherit the start time from the original set

status_option
enum {ACTIVE, PAUSED, INHERITED_FROM_SOURCE}
Default value: PAUSED

ACTIVE: the copied adset will have active status. PAUSED: the copied adset will have paused status. INHERITED_FROM_SOURCE: the copied adset will have the status from the original set.

Return Type

This endpoint supports read-after-write and will read the node represented by copied_adset_id in the return type.
Struct {
copied_adset_id: numeric string,
ad_object_ids: List [
Struct {
ad_object_type: enum {unique_adcreative, ad, ad_set, campaign, opportunities, topline, ad_account},
source_id: numeric string,
copied_id: numeric string,
}
],
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
294Managing advertisements requires an access token with the extended permission for ads_management
You can make a POST request to adsets edge from the following paths:
When posting to this edge, an AdSet will be created.

Example

Graph API Explorer
POST /v5.0/act_<AD_ACCOUNT_ID>/adsets HTTP/1.1
Host: graph.facebook.com

name=My+First+AdSet&lifetime_budget=20000&start_time=2019-12-14T01%3A59%3A32-0800&end_time=2019-12-21T01%3A59%3A32-0800&campaign_id=%3CAD_CAMPAIGN_ID%3E&bid_amount=500&billing_event=IMPRESSIONS&optimization_goal=POST_ENGAGEMENT&targeting=%7B%22age_min%22%3A20%2C%22age_max%22%3A24%2C%22behaviors%22%3A%5B%7B%22id%22%3A6002714895372%2C%22name%22%3A%22All+travelers%22%7D%5D%2C%22genders%22%3A%5B1%5D%2C%22geo_locations%22%3A%7B%22countries%22%3A%5B%22US%22%5D%2C%22regions%22%3A%5B%7B%22key%22%3A%224081%22%7D%5D%2C%22cities%22%3A%5B%7B%22key%22%3A%22777934%22%2C%22radius%22%3A10%2C%22distance_unit%22%3A%22mile%22%7D%5D%7D%2C%22interests%22%3A%5B%7B%22id%22%3A%22%3CINTEREST_ID%3E%22%2C%22name%22%3A%22%3CINTEREST_NAME%3E%22%7D%5D%2C%22life_events%22%3A%5B%7B%22id%22%3A6002714398172%2C%22name%22%3A%22Newlywed+%281+year%29%22%7D%5D%2C%22publisher_platforms%22%3A%5B%22facebook%22%2C%22audience_network%22%5D%7D&status=PAUSED
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/act_<AD_ACCOUNT_ID>/adsets',
    array (
      'name' => 'My First AdSet',
      'lifetime_budget' => '20000',
      'start_time' => '2019-12-14T01:59:32-0800',
      'end_time' => '2019-12-21T01:59:32-0800',
      'campaign_id' => '<AD_CAMPAIGN_ID>',
      'bid_amount' => '500',
      'billing_event' => 'IMPRESSIONS',
      'optimization_goal' => 'POST_ENGAGEMENT',
      'targeting' => '{"age_min":20,"age_max":24,"behaviors":[{"id":6002714895372,"name":"All travelers"}],"genders":[1],"geo_locations":{"countries":["US"],"regions":[{"key":"4081"}],"cities":[{"key":"777934","radius":10,"distance_unit":"mile"}]},"interests":[{"id":"<INTEREST_ID>","name":"<INTEREST_NAME>"}],"life_events":[{"id":6002714398172,"name":"Newlywed (1 year)"}],"publisher_platforms":["facebook","audience_network"]}',
      'status' => 'PAUSED',
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/act_<AD_ACCOUNT_ID>/adsets",
    "POST",
    {
        "name": "My First AdSet",
        "lifetime_budget": "20000",
        "start_time": "2019-12-14T01:59:32-0800",
        "end_time": "2019-12-21T01:59:32-0800",
        "campaign_id": "<AD_CAMPAIGN_ID>",
        "bid_amount": "500",
        "billing_event": "IMPRESSIONS",
        "optimization_goal": "POST_ENGAGEMENT",
        "targeting": "{\"age_min\":20,\"age_max\":24,\"behaviors\":[{\"id\":6002714895372,\"name\":\"All travelers\"}],\"genders\":[1],\"geo_locations\":{\"countries\":[\"US\"],\"regions\":[{\"key\":\"4081\"}],\"cities\":[{\"key\":\"777934\",\"radius\":10,\"distance_unit\":\"mile\"}]},\"interests\":[{\"id\":\"<INTEREST_ID>\",\"name\":\"<INTEREST_NAME>\"}],\"life_events\":[{\"id\":6002714398172,\"name\":\"Newlywed (1 year)\"}],\"publisher_platforms\":[\"facebook\",\"audience_network\"]}",
        "status": "PAUSED"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("name", "My First AdSet");
params.putString("lifetime_budget", "20000");
params.putString("start_time", "2019-12-14T01:59:32-0800");
params.putString("end_time", "2019-12-21T01:59:32-0800");
params.putString("campaign_id", "<AD_CAMPAIGN_ID>");
params.putString("bid_amount", "500");
params.putString("billing_event", "IMPRESSIONS");
params.putString("optimization_goal", "POST_ENGAGEMENT");
params.putString("targeting", "{\"age_min\":20,\"age_max\":24,\"behaviors\":[{\"id\":6002714895372,\"name\":\"All travelers\"}],\"genders\":[1],\"geo_locations\":{\"countries\":[\"US\"],\"regions\":[{\"key\":\"4081\"}],\"cities\":[{\"key\":\"777934\",\"radius\":10,\"distance_unit\":\"mile\"}]},\"interests\":[{\"id\":\"<INTEREST_ID>\",\"name\":\"<INTEREST_NAME>\"}],\"life_events\":[{\"id\":6002714398172,\"name\":\"Newlywed (1 year)\"}],\"publisher_platforms\":[\"facebook\",\"audience_network\"]}");
params.putString("status", "PAUSED");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/act_<AD_ACCOUNT_ID>/adsets",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"name": @"My First AdSet",
  @"lifetime_budget": @"20000",
  @"start_time": @"2019-12-14T01:59:32-0800",
  @"end_time": @"2019-12-21T01:59:32-0800",
  @"campaign_id": @"<AD_CAMPAIGN_ID>",
  @"bid_amount": @"500",
  @"billing_event": @"IMPRESSIONS",
  @"optimization_goal": @"POST_ENGAGEMENT",
  @"targeting": @"{\"age_min\":20,\"age_max\":24,\"behaviors\":[{\"id\":6002714895372,\"name\":\"All travelers\"}],\"genders\":[1],\"geo_locations\":{\"countries\":[\"US\"],\"regions\":[{\"key\":\"4081\"}],\"cities\":[{\"key\":\"777934\",\"radius\":10,\"distance_unit\":\"mile\"}]},\"interests\":[{\"id\":\"<INTEREST_ID>\",\"name\":\"<INTEREST_NAME>\"}],\"life_events\":[{\"id\":6002714398172,\"name\":\"Newlywed (1 year)\"}],\"publisher_platforms\":[\"facebook\",\"audience_network\"]}",
  @"status": @"PAUSED",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/adsets"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl -X POST \
  -F 'name="My First AdSet"' \
  -F 'lifetime_budget=20000' \
  -F 'start_time="2019-12-14T01:59:32-0800"' \
  -F 'end_time="2019-12-21T01:59:32-0800"' \
  -F 'campaign_id="<AD_CAMPAIGN_ID>"' \
  -F 'bid_amount=500' \
  -F 'billing_event="IMPRESSIONS"' \
  -F 'optimization_goal="POST_ENGAGEMENT"' \
  -F 'targeting={
       "age_min": 20,
       "age_max": 24,
       "behaviors": [
         {
           "id": 6002714895372,
           "name": "All travelers"
         }
       ],
       "genders": [
         1
       ],
       "geo_locations": {
         "countries": [
           "US"
         ],
         "regions": [
           {
             "key": "4081"
           }
         ],
         "cities": [
           {
             "key": "777934",
             "radius": 10,
             "distance_unit": "mile"
           }
         ]
       },
       "interests": [
         {
           "id": "<INTEREST_ID>",
           "name": "<INTEREST_NAME>"
         }
       ],
       "life_events": [
         {
           "id": 6002714398172,
           "name": "Newlywed (1 year)"
         }
       ],
       "publisher_platforms": [
         "facebook",
         "audience_network"
       ]
     }' \
  -F 'status="PAUSED"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v5.0/act_<AD_ACCOUNT_ID>/adsets
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

ParameterDescription
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
timezone_type
enum {USER, ADVERTISER}
Default value: USER

attribution_spec
list<JSON object>

Conversion attribution spec used for attributing conversions for optimization. Supported window lengths differ by optimization goal and campaign objective. See Validation, Attribution Spec.

event_type
enum {CLICK_THROUGH, VIEW_THROUGH}

Required
window_days
int64

Required
bid_amount
integer

Bid cap or target cost for this ad set. The bid cap used in a lowest cost bid strategy is defined as the maximum bid you want to pay for a result based on your optimization_goal. The target cost used in a target cost bid strategy lets Facebook bid to meet your target on average and keep costs stable as you spend. If an ad level bid_amount is specified, updating this value will overwrite the previous ad level bid. Unless you are using Reach and Frequency, bid_amount is required if bid_strategy is set to LOWEST_COST_WITH_BID_CAP, TARGET_COST, and COST_CAP.
The bid amount's unit is cents for currencies like USD, EUR, and the basic unit for currencies like JPY, KRW. The bid amount for ads with IMPRESSION or REACH as billing_event is per 1,000 occurrences, and has to be at least 2 US cents or more. For ads with other billing_events, the bid amount 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.

bid_strategy
enum{LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, TARGET_COST}

Choose bid strategy for this ad set to suit your specific business goals. Each strategy has tradeoffs and may be available for certain optimization_goals:
LOWEST_COST_WITHOUT_CAP: Designed to get the most results for your budget based on your ad set optimization_goal without limiting your bid amount. This is the best strategy if you care most about cost efficiency. However with this strategy it may be harder to get stable average costs as you spend. This strategy is also known as automatic bidding. Learn more in Ads Help Center, About bid strategies: Lowest cost.
LOWEST_COST_WITH_BID_CAP: Designed to get the most results for your budget based on your ad set optimization_goal while limiting actual bid to your specified amount. With a bid cap you have more control over your cost per actual optimization event. However if you set a limit which is too low you may get less ads delivery. If you select this, you must provide a bid cap with the bid_amount field. Note: during creation this bid strategy is set if you provide bid_amount only. This strategy is also known as manual maximum-cost bidding. Learn more in Ads Help Center, About bid strategies: Lowest cost.
TARGET_COST: Maintains a stable average cost based on your optimization_goal as you raise your ad set budget. Select this strategy if you care most about maintaining stable average costs for your ads. However, note that this strategy may be less cost-efficient than the lowest cost strategy. If you select this, you must provide a target cost with the bid_amount field. Target cost bid strategy is also known as manual average-cost bidding. Learn more in Ads Help Center, About bid strategies: Target cost.
Note: If you enable campaign budget optimization, you should set bid_strategy at the parent campaign level.

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

The billing event that this ad set 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 your video ads for at least 10 seconds.
THRUPLAY: Pay for ads that are played to completion, or played for at least 15 seconds.

campaign_id
numeric string or integer

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

campaign_spec
Campaign spec

Provide name, objective and buying_type for a campaign you want to create. Otherwise you need to provide campaign_id for an existing ad campaign. For example:
-F 'campaign_spec={
  "name": "Inline created campaign",
  "objective": "CONVERSIONS",
  "buying_type": "AUCTION"
}'

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 daily_budget or lifetime_budget must be greater than 0.

daily_imps
int64

Daily impressions. Available only for campaigns with buying_type=FIXED_CPM

daily_min_spend_target
int64

Daily minimum spend target of the ad set defined in your account currency. To use this field, daily budget must be specified in the Campaign. This target is not a guarantee but our best effort.

daily_spend_cap
int64

Daily spend cap of the ad set defined in your account currency. To use this field, daily budget must be specified in the Campaign. Set the value to 922337203685478 to remove the spend cap.

destination_type
enum{UNDEFINED, WEBSITE, APP, MESSENGER, APPLINKS_AUTOMATIC, FACEBOOK}

Destination of ads in this Ad Set (e.g. Website, App, Messenger)

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 currently supported, this array has no more than one element. Writes to this field are only available in ad sets where REACH is the objective.

event
enum{IMPRESSIONS, VIDEO_VIEWS, VIDEO_VIEWS_2S, VIDEO_VIEWS_15S}

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, between 1 and 90 (inclusive)

Required
is_dynamic_creative
boolean

Indicates the ad set must only be used for dynamic creatives. Dynamic creative ads can be created in this ad set. Defaults to false

lifetime_budget
int64

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

lifetime_imps
int64

Lifetime impressions. Available only for campaigns with buying_type=FIXED_CPM

lifetime_min_spend_target
int64

Lifetime minimum spend target of the ad set defined in your account currency. To use this field, lifetime budget must be specified in the Campaign. This target is not a guarantee but our best effort.

lifetime_spend_cap
int64

Lifetime spend cap of the ad set defined in your account currency. To use this field, lifetime budget must be specified in the Campaign. Set the value to 922337203685478 to remove the spend cap.

name
string

Ad set name, max length of 400 characters.

RequiredSupports Emoji
optimization_goal
enum{NONE, APP_INSTALLS, BRAND_AWARENESS, AD_RECALL_LIFT, CLICKS, ENGAGED_USERS, EVENT_RESPONSES, IMPRESSIONS, LEAD_GENERATION, LINK_CLICKS, OFFER_CLAIMS, OFFSITE_CONVERSIONS, PAGE_ENGAGEMENT, PAGE_LIKES, POST_ENGAGEMENT, REACH, SOCIAL_IMPRESSIONS, VIDEO_VIEWS, APP_DOWNLOADS, TWO_SECOND_CONTINUOUS_VIDEO_VIEWS, LANDING_PAGE_VIEWS, VALUE, THRUPLAY, REPLIES, DERIVED_EVENTS}

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.
ENGAGED_USERS: Will optimize for people more likely to take a particular action in your app.
EVENT_RESPONSES: Will optimize for people more likely to attend your event.
IMPRESSIONS: Will show the ads as many times as possible.
LEAD_GENERATION: Will optimize for people more likely to fill out a lead generation form.
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_CONVERSIONS: Will optimize for people more likely to make a conversion in the site
PAGE_ENGAGEMENT: Will optimize for people more likely to engage with your page.
PAGE_LIKES: Will optimize for people more likely to like your page.
POST_ENGAGEMENT: Will 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: Will optimize delivery of your ads to people who are more likely to watch videos for at least 10 seconds.
VALUE: Will optimize for maximum total purchase value within the specified attribution window.
THRUPLAY: Will optimize delivery of your ads to people are more likely to play your ad to completion, or play it for at least 15 seconds.

optimization_sub_event
enum{NONE, VIDEO_SOUND_ON, TRIP_CONSIDERATION, TRAVEL_INTENT, TRAVEL_INTENT_NO_DESTINATION_INTENT, TRAVEL_INTENT_BUCKET_01, TRAVEL_INTENT_BUCKET_02, TRAVEL_INTENT_BUCKET_03, TRAVEL_INTENT_BUCKET_04, TRAVEL_INTENT_BUCKET_05}

Optimization sub event for a specific optimization goal (ex: Sound-On event for Video-View-2s optimization goal)

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
  • application_id, object_store_url, and custom_event_type for mobile app events
  • offline_conversion_data_set_id (Offline dataset ID) and custom_event_type for offline conversions
PAGE_LIKES
page_id
OFFER_CLAIMS
page_id
LINK_CLICKS
application_id and object_store_url for mobile app or Canvas app engagement link clicks
APP_INSTALLS
application_id and object_store_url
or application_id, object_store_url, and custom_event_type if the optimization_goal is OFFSITE_CONVERSIONS
PRODUCT_CATALOG_SALES
product_set_id,
or product_set_id and custom_event_type

When optimization_goal is LEAD_GENERATION, page_id needs to be passed as promoted_object.

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{RATE, TUTORIAL_COMPLETION, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, LEAD, COMPLETE_REGISTRATION, CONTENT_VIEW, SEARCH, SERVICE_BOOKING_REQUEST, MESSAGING_CONVERSATION_STARTED_7D, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, LISTING_INTERACTION, D2_RETENTION, D7_RETENTION, OTHER}

The event from an App Event of a mobile app, not in the standard event list.

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
Page ID

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_item_id
numeric string or integer

The ID of the product item.

instagram_profile_id
numeric string or integer

The ID of the instagram profile id.

product_set_id
numeric string or integer

The ID of a Product Set within an Ad Set level Product Catalog. Used with Dynamic Product Ads.

event_id
numeric string or integer

The ID of a Facebook Event

offline_conversion_data_set_id
numeric string or integer

The ID of the offline dataset.

fundraiser_campaign_id
numeric string or integer

The ID of the fundraiser campaign.

custom_event_str
string

The event from an App Event of a mobile app, not in the standard event list.

omnichannel_object
Object

app
list<Object>

application_id
App ID

custom_event_type
enum {JOB_ALERT_SUBSCRIBE, JOB_APPLICATION_CREATE, JOB_APPLICATION_FORM_IMPRESSION, JOB_BROWSER_IMPRESSION, JOB_OPENING_DETAIL_VIEW_IMPRESSION, ACTIVATE_APP, COMPLETE_REGISTRATION, CONTENT_VIEW, ONSITE_APP_CONTENT_VIEW, ONSITE_WEB_CONTENT_VIEW, ONSITE_WEB_APP_CONTENT_VIEW, SEARCH, RATE, TUTORIAL_COMPLETION, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, RECURRING_SUBSCRIPTION_PAYMENT, CANCEL_SUBSCRIPTION, VISIT_LOCATION, AD_CLICK, AD_IMPRESSION, ADD_TO_CART, ONSITE_APP_ADD_TO_CART, ONSITE_WEB_ADD_TO_CART, ONSITE_WEB_APP_ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, ONSITE_APP_PURCHASE, ONSITE_WEB_PURCHASE, ONSITE_WEB_APP_PURCHASE, MESSAGE_TO_BUY, LEAD, ONSITE_WEB_LEAD, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, FLOW_COMPLETE, SERVICE_BOOKING_REQUEST, MESSAGING_ACCEPT, MESSAGING_BLOCK, MESSAGING_DELETE_THREAD, MESSAGING_MARK_SPAM, MESSAGING_REPLY, MESSAGING_FIRST_REPLY, MESSAGING_OPEN_THREAD, MESSAGING_IGNORE_REQUEST, MESSAGING_PROMOTIONAL_OFF, MESSAGING_READ_RECEIPT, MESSAGING_DELIVERY_RECEIPT, MESSAGING_DELETE_MESSAGE, MESSAGING_CONVERSATION_STARTED_7D, MESSAGING_DEEP_CONVERSATION, MESSAGING_AUTOMATED_FLOW_COMPLETE, MESSAGING_AUTOMATED_FLOW_CANCELLED, MESSENGER_RECEIPT_TEMPLATE, REFERRAL_SENDER_INVITES_SENT, REFERRAL_SENDER_MESSAGE_SENT, REFERRAL_RECEIVER_IMPRESSION, REFERRAL_RECEIVER_CLICK, VIDEO_HOME_SELECTED, VIDEO_HOME_WATCHLIST, VIDEO_HOME_EXPLORE, VIDEO_HOME_PLAYER_START, VIDEO_HOME_90_SECOND_VIEW, FUNDRAISER_CREATE, MESSENGER_CONNECTED_CALL, MESSENGER_MISSED_CALL, D2_RETENTION, D7_RETENTION, MOVIE_SHOWTIME_CLICK, LISTING_INTERACTION, PDP_VIEW, CLICK_TO_CALL, CLICK_TO_WEBSITE, POST_SHARE, OTHER}

object_store_urls
list<string>

pixel
list<Object>

custom_event_type
enum {JOB_ALERT_SUBSCRIBE, JOB_APPLICATION_CREATE, JOB_APPLICATION_FORM_IMPRESSION, JOB_BROWSER_IMPRESSION, JOB_OPENING_DETAIL_VIEW_IMPRESSION, ACTIVATE_APP, COMPLETE_REGISTRATION, CONTENT_VIEW, ONSITE_APP_CONTENT_VIEW, ONSITE_WEB_CONTENT_VIEW, ONSITE_WEB_APP_CONTENT_VIEW, SEARCH, RATE, TUTORIAL_COMPLETION, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, RECURRING_SUBSCRIPTION_PAYMENT, CANCEL_SUBSCRIPTION, VISIT_LOCATION, AD_CLICK, AD_IMPRESSION, ADD_TO_CART, ONSITE_APP_ADD_TO_CART, ONSITE_WEB_ADD_TO_CART, ONSITE_WEB_APP_ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, ONSITE_APP_PURCHASE, ONSITE_WEB_PURCHASE, ONSITE_WEB_APP_PURCHASE, MESSAGE_TO_BUY, LEAD, ONSITE_WEB_LEAD, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, FLOW_COMPLETE, SERVICE_BOOKING_REQUEST, MESSAGING_ACCEPT, MESSAGING_BLOCK, MESSAGING_DELETE_THREAD, MESSAGING_MARK_SPAM, MESSAGING_REPLY, MESSAGING_FIRST_REPLY, MESSAGING_OPEN_THREAD, MESSAGING_IGNORE_REQUEST, MESSAGING_PROMOTIONAL_OFF, MESSAGING_READ_RECEIPT, MESSAGING_DELIVERY_RECEIPT, MESSAGING_DELETE_MESSAGE, MESSAGING_CONVERSATION_STARTED_7D, MESSAGING_DEEP_CONVERSATION, MESSAGING_AUTOMATED_FLOW_COMPLETE, MESSAGING_AUTOMATED_FLOW_CANCELLED, MESSENGER_RECEIPT_TEMPLATE, REFERRAL_SENDER_INVITES_SENT, REFERRAL_SENDER_MESSAGE_SENT, REFERRAL_RECEIVER_IMPRESSION, REFERRAL_RECEIVER_CLICK, VIDEO_HOME_SELECTED, VIDEO_HOME_WATCHLIST, VIDEO_HOME_EXPLORE, VIDEO_HOME_PLAYER_START, VIDEO_HOME_90_SECOND_VIEW, FUNDRAISER_CREATE, MESSENGER_CONNECTED_CALL, MESSENGER_MISSED_CALL, D2_RETENTION, D7_RETENTION, MOVIE_SHOWTIME_CLICK, LISTING_INTERACTION, PDP_VIEW, CLICK_TO_CALL, CLICK_TO_WEBSITE, POST_SHARE, OTHER}

pixel_id
Ads Pixel ID

pixel_rule
string

rf_prediction_id
numeric string or integer

Reach and frequency prediction ID

source_adset_id
numeric string or integer

The source adset id that this ad is copied from (if applicable).

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 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.

time_start
datetime

Time start

time_stop
datetime

Time stop

tune_for_category
enum{NONE, EMPLOYMENT, HOUSING, CREDIT}

tune_for_category

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
105The number of parameters exceeded the maximum for this operation
80004There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
294Managing advertisements requires an access token with the extended permission for ads_management
900No such application exists.
2626The request for a reach frequency campaign has failed.
2625The request for a reach frequency campaign is invalid.

Updating

Examples

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

$adset = new AdSet(<AD_SET_ID>, 'act_<AD_ACCOUNT_ID>');
$adset->setData(array(
  AdSetFields::BILLING_EVENT => AdSetBillingEventValues::IMPRESSIONS,
  AdSetFields::OPTIMIZATION_GOAL => AdSetOptimizationGoalValues::LINK_CLICKS,
  AdSetFields::BID_AMOUNT => 200,
));

$adset->update();
from facebookads.adobjects.adset import AdSet

adset = AdSet(fbid=<AD_SET_ID>, parent_id='act_<AD_ACCOUNT_ID>')
adset.update({
    AdSet.Field.optimization_goal: AdSet.OptimizationGoal.link_clicks,
    AdSet.Field.billing_event: AdSet.BillingEvent.impressions,
    AdSet.Field.bid_amount: 200,
})
adset.remote_update()
new AdSet(<AD_SET_ID>, context).update()
  .setBillingEvent(AdSet.EnumBillingEvent.VALUE_IMPRESSIONS)
  .setOptimizationGoal(AdSet.EnumOptimizationGoal.VALUE_LINK_CLICKS)
  .setBidAmount(200L)
  .execute();
curl \
  -F 'billing_event=IMPRESSIONS' \
  -F 'optimization_goal=LINK_CLICKS' \
  -F 'bid_amount=200' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_SET_ID>

To update the end_time of an ad set, 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 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 two considerations to take into account when adjusting an ad set's budget value or budget type:

  • 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.
  • 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.
You can update an AdSet by making a POST request to /{ad_set_id}.

Example

Graph API Explorer
POST /v5.0/<AD_SET_ID>/ HTTP/1.1
Host: graph.facebook.com

bid_adjustments=%7B%22user_groups%22%3A%7B%22user_bucket%22%3A%7B%22event_sources%22%3A%5B%22%3CPIXEL_ID%3E%22%2C%22%3CAPP_ID%3E%22%5D%2C%221%22%3A0.1%2C%222%22%3A0.2%2C%223%22%3A0.3%2C%22default%22%3A%7B%22gender%22%3A%7B%22male%22%3A0.99%2C%22female%22%3A0.12%7D%7D%7D%7D%7D
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/<AD_SET_ID>/',
    array (
      'bid_adjustments' => '{"user_groups":{"user_bucket":{"event_sources":["<PIXEL_ID>","<APP_ID>"],"1":0.1,"2":0.2,"3":0.3,"default":{"gender":{"male":0.99,"female":0.12}}}}}',
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/<AD_SET_ID>/",
    "POST",
    {
        "bid_adjustments": "{\"user_groups\":{\"user_bucket\":{\"event_sources\":[\"<PIXEL_ID>\",\"<APP_ID>\"],\"1\":0.1,\"2\":0.2,\"3\":0.3,\"default\":{\"gender\":{\"male\":0.99,\"female\":0.12}}}}}"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("bid_adjustments", "{\"user_groups\":{\"user_bucket\":{\"event_sources\":[\"<PIXEL_ID>\",\"<APP_ID>\"],\"1\":0.1,\"2\":0.2,\"3\":0.3,\"default\":{\"gender\":{\"male\":0.99,\"female\":0.12}}}}}");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/<AD_SET_ID>/",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"bid_adjustments": @"{\"user_groups\":{\"user_bucket\":{\"event_sources\":[\"<PIXEL_ID>\",\"<APP_ID>\"],\"1\":0.1,\"2\":0.2,\"3\":0.3,\"default\":{\"gender\":{\"male\":0.99,\"female\":0.12}}}}}",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/<AD_SET_ID>/"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl -X POST \
  -F 'bid_adjustments={
       "user_groups": {
         "user_bucket": {
           "event_sources": [
             "<PIXEL_ID>",
             "<APP_ID>"
           ],
           "1": 0.1,
           "2": 0.2,
           "3": 0.3,
           "default": {
             "gender": {
               "male": 0.99,
               "female": 0.12
             }
           }
         }
       }
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v5.0/<AD_SET_ID>/
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

ParameterDescription
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
timezone_type
enum {USER, ADVERTISER}
Default value: USER

attribution_spec
list<JSON object>

Conversion attribution spec used for attributing conversions for optimization. Supported window lengths differ by optimization goal and campaign objective. See Validation, Attribution Spec.

event_type
enum {CLICK_THROUGH, VIEW_THROUGH}

Required
window_days
int64

Required
bid_amount
integer

Bid cap or target cost for this ad set. The bid cap used in a lowest cost bid strategy is defined as the maximum bid you want to pay for a result based on your optimization_goal. The target cost used in a target cost bid strategy lets Facebook bid to meet your target on average and keep costs stable as you spend. If an ad level bid_amount is specified, updating this value will overwrite the previous ad level bid. Unless you are using Reach and Frequency, bid_amount is required if the bid_strategy is set to LOWEST_COST_WITH_BID_CAP, TARGET_COST, and COST_CAP.
The bid amount's unit is cents for currencies like USD, EUR, and the basic unit for currencies like JPY, KRW. The bid amount for ads with IMPRESSION or REACH as billing_event is per 1,000 occurrences, and has to be at least 2 US cents or more. For ads with other billing_events, the bid amount 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.

bid_strategy
enum{LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, TARGET_COST}

Choose bid strategy for this ad set to suit your specific business goals. Each strategy has tradeoffs and may be available for certain optimization_goals:
LOWEST_COST_WITHOUT_CAP: Designed to get the most results for your budget based on your ad set optimization_goal without limiting your bid amount. This is the best strategy if you care most about cost efficiency. However with this strategy it may be harder to get stable average costs as you spend. This strategy is also known as automatic bidding. Learn more in Ads Help Center, About bid strategies: Lowest cost.
LOWEST_COST_WITH_BID_CAP: Designed to get the most results for your budget based on your ad set optimization_goal while limiting actual bid to your specified amount. With a bid cap you have more control over your cost per actual optimization event. However if you set a limit which is too low you may get less ads delivery. If you select this, you must provide a bid cap with the bid_amount field. Note: during creation this bid strategy is set if you provide bid_amount only. This strategy is also known as manual maximum-cost bidding. Learn more in Ads Help Center, About bid strategies: Lowest cost.
TARGET_COST: Maintains a stable average cost based on your optimization_goal as you raise your ad set budget. Select this strategy if you care most about maintaining stable average costs for your ads. However, note that this strategy may be less cost-efficient than the lowest cost strategy. If you select this, you must provide a target cost with the bid_amount field. Target cost bid strategy is also known as manual average-cost bidding. Learn more in Ads Help Center, About bid strategies: Target cost.
Note: If you enable campaign budget optimization, you should set bid_strategy at the parent campaign level.

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

The billing event that this ad set 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 your video ads for at least 10 seconds.
THRUPLAY: Pay for ads that are played to completion, or played for at least 15 seconds.

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 daily_budget or lifetime_budget must be greater than 0.

daily_imps
int64

Daily impressions. Available only for campaigns with buying_type=FIXED_CPM

daily_min_spend_target
int64

Daily minimum spend target of the ad set defined in your account currency. To use this field, daily budget must be specified in the Campaign. This target is not a guarantee but our best effort.

daily_spend_cap
int64

Daily spend cap of the ad set defined in your account currency. To use this field, daily budget must be specified in the Campaign. Set the value to 922337203685478 to remove the spend cap.

destination_type
enum{UNDEFINED, WEBSITE, APP, MESSENGER, APPLINKS_AUTOMATIC, FACEBOOK}

Destination of ads in this Ad Set. Examples are Website, App and Messenger.

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.

lifetime_budget
int64

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

lifetime_imps
int64

Lifetime impressions. Available only for campaigns with buying_type=FIXED_CPM

lifetime_min_spend_target
int64

Lifetime minimum spend target of the ad set defined in your account currency. To use this field, lifetime budget must be specified in the Campaign. This target is not a guarantee but our best effort.

lifetime_spend_cap
int64

Lifetime spend cap of the ad set defined in your account currency. To use this field, lifetime budget must be specified in the Campaign. Set the value to 922337203685478 to remove the spend cap.

name
string

Ad set name, max length of 400 characters.

Supports Emoji
optimization_goal
enum{NONE, APP_INSTALLS, BRAND_AWARENESS, AD_RECALL_LIFT, CLICKS, ENGAGED_USERS, EVENT_RESPONSES, IMPRESSIONS, LEAD_GENERATION, LINK_CLICKS, OFFER_CLAIMS, OFFSITE_CONVERSIONS, PAGE_ENGAGEMENT, PAGE_LIKES, POST_ENGAGEMENT, REACH, SOCIAL_IMPRESSIONS, VIDEO_VIEWS, APP_DOWNLOADS, TWO_SECOND_CONTINUOUS_VIDEO_VIEWS, LANDING_PAGE_VIEWS, VALUE, THRUPLAY, REPLIES, DERIVED_EVENTS}

What the ad set is optimizing for.
APP_INSTALLS: Optimizes for people more likely to install your app.
BRAND_AWARENESS: Optimizes to reach the most users to spend at least a minimum amount of time on the image or video. You cannot set bid_amount.
ENGAGED_USERS: Optimizes for people more likely to take a particular action in your app.
EVENT_RESPONSES: Optimizes for people more likely to attend your event.
IMPRESSIONS: Shows the ads as many times as possible.
LEAD_GENERATION: Optimizes for people more likely to fill out a lead generation form.
LINK_CLICKS: Optimizes for people more likely to click in the link of the ad.
OFFER_CLAIMS: Optimizes for people more likely to claim the offer.
OFFSITE_CONVERSIONS: Optimizes for people more likely to make a conversion in the site
PAGE_ENGAGEMENT: Optimizes for people more likely to engage with your page.
PAGE_LIKES: Optimizes for people more likely to like your page.
POST_ENGAGEMENT: Optimizes for people more likely to engage with your post.
REACH: Optimizes 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, like 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: Optimizes delivery of your ads to people who are more likely to watch videos for at least 10 seconds.
VALUE: Optimizes for maximum total purchase value within the specified attribution window.
THRUPLAY: Optimizes delivery of your ads to people are more likely to play your ad to completion, or play it for at least 15 seconds.

optimization_sub_event
enum{NONE, VIDEO_SOUND_ON, TRIP_CONSIDERATION, TRAVEL_INTENT, TRAVEL_INTENT_NO_DESTINATION_INTENT, TRAVEL_INTENT_BUCKET_01, TRAVEL_INTENT_BUCKET_02, TRAVEL_INTENT_BUCKET_03, TRAVEL_INTENT_BUCKET_04, TRAVEL_INTENT_BUCKET_05}

Optimization sub event for a specific optimization goal. For example sound-on event for Video-View-2s optimization goal.

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
  • application_id, object_store_url, and custom_event_type for mobile app events
  • offline_conversion_data_set_id (Offline dataset ID) and custom_event_type for offline conversions
PAGE_LIKES
page_id
OFFER_CLAIMS
page_id
LINK_CLICKS
application_id and object_store_url for mobile app or Canvas app engagement link clicks
APP_INSTALLS
application_id and object_store_url
or application_id, object_store_url, and custom_event_type if the optimization_goal is OFFSITE_CONVERSIONS
PRODUCT_CATALOG_SALES
product_set_id,
or product_set_id and custom_event_type

When optimization_goal is LEAD_GENERATION, page_id needs to be passed as promoted_object.

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{RATE, TUTORIAL_COMPLETION, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, LEAD, COMPLETE_REGISTRATION, CONTENT_VIEW, SEARCH, SERVICE_BOOKING_REQUEST, MESSAGING_CONVERSATION_STARTED_7D, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, LISTING_INTERACTION, D2_RETENTION, D7_RETENTION, OTHER}

The event from an App Event of a mobile app, not in the standard event list.

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
Page ID

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_item_id
numeric string or integer

The ID of the product item.

instagram_profile_id
numeric string or integer

The ID of the instagram profile id.

product_set_id
numeric string or integer

The ID of a Product Set within an Ad Set level Product Catalog. Used with Dynamic Product Ads.

event_id
numeric string or integer

The ID of a Facebook Event

offline_conversion_data_set_id
numeric string or integer

The ID of the offline dataset.

fundraiser_campaign_id
numeric string or integer

The ID of the fundraiser campaign.

custom_event_str
string

The event from an App Event of a mobile app, not in the standard event list.

omnichannel_object
Object

app
list<Object>

application_id
App ID

custom_event_type
enum {JOB_ALERT_SUBSCRIBE, JOB_APPLICATION_CREATE, JOB_APPLICATION_FORM_IMPRESSION, JOB_BROWSER_IMPRESSION, JOB_OPENING_DETAIL_VIEW_IMPRESSION, ACTIVATE_APP, COMPLETE_REGISTRATION, CONTENT_VIEW, ONSITE_APP_CONTENT_VIEW, ONSITE_WEB_CONTENT_VIEW, ONSITE_WEB_APP_CONTENT_VIEW, SEARCH, RATE, TUTORIAL_COMPLETION, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, RECURRING_SUBSCRIPTION_PAYMENT, CANCEL_SUBSCRIPTION, VISIT_LOCATION, AD_CLICK, AD_IMPRESSION, ADD_TO_CART, ONSITE_APP_ADD_TO_CART, ONSITE_WEB_ADD_TO_CART, ONSITE_WEB_APP_ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, ONSITE_APP_PURCHASE, ONSITE_WEB_PURCHASE, ONSITE_WEB_APP_PURCHASE, MESSAGE_TO_BUY, LEAD, ONSITE_WEB_LEAD, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, FLOW_COMPLETE, SERVICE_BOOKING_REQUEST, MESSAGING_ACCEPT, MESSAGING_BLOCK, MESSAGING_DELETE_THREAD, MESSAGING_MARK_SPAM, MESSAGING_REPLY, MESSAGING_FIRST_REPLY, MESSAGING_OPEN_THREAD, MESSAGING_IGNORE_REQUEST, MESSAGING_PROMOTIONAL_OFF, MESSAGING_READ_RECEIPT, MESSAGING_DELIVERY_RECEIPT, MESSAGING_DELETE_MESSAGE, MESSAGING_CONVERSATION_STARTED_7D, MESSAGING_DEEP_CONVERSATION, MESSAGING_AUTOMATED_FLOW_COMPLETE, MESSAGING_AUTOMATED_FLOW_CANCELLED, MESSENGER_RECEIPT_TEMPLATE, REFERRAL_SENDER_INVITES_SENT, REFERRAL_SENDER_MESSAGE_SENT, REFERRAL_RECEIVER_IMPRESSION, REFERRAL_RECEIVER_CLICK, VIDEO_HOME_SELECTED, VIDEO_HOME_WATCHLIST, VIDEO_HOME_EXPLORE, VIDEO_HOME_PLAYER_START, VIDEO_HOME_90_SECOND_VIEW, FUNDRAISER_CREATE, MESSENGER_CONNECTED_CALL, MESSENGER_MISSED_CALL, D2_RETENTION, D7_RETENTION, MOVIE_SHOWTIME_CLICK, LISTING_INTERACTION, PDP_VIEW, CLICK_TO_CALL, CLICK_TO_WEBSITE, POST_SHARE, OTHER}

object_store_urls
list<string>

pixel
list<Object>

custom_event_type
enum {JOB_ALERT_SUBSCRIBE, JOB_APPLICATION_CREATE, JOB_APPLICATION_FORM_IMPRESSION, JOB_BROWSER_IMPRESSION, JOB_OPENING_DETAIL_VIEW_IMPRESSION, ACTIVATE_APP, COMPLETE_REGISTRATION, CONTENT_VIEW, ONSITE_APP_CONTENT_VIEW, ONSITE_WEB_CONTENT_VIEW, ONSITE_WEB_APP_CONTENT_VIEW, SEARCH, RATE, TUTORIAL_COMPLETION, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, RECURRING_SUBSCRIPTION_PAYMENT, CANCEL_SUBSCRIPTION, VISIT_LOCATION, AD_CLICK, AD_IMPRESSION, ADD_TO_CART, ONSITE_APP_ADD_TO_CART, ONSITE_WEB_ADD_TO_CART, ONSITE_WEB_APP_ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE, ONSITE_APP_PURCHASE, ONSITE_WEB_PURCHASE, ONSITE_WEB_APP_PURCHASE, MESSAGE_TO_BUY, LEAD, ONSITE_WEB_LEAD, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, SPENT_CREDITS, FLOW_COMPLETE, SERVICE_BOOKING_REQUEST, MESSAGING_ACCEPT, MESSAGING_BLOCK, MESSAGING_DELETE_THREAD, MESSAGING_MARK_SPAM, MESSAGING_REPLY, MESSAGING_FIRST_REPLY, MESSAGING_OPEN_THREAD, MESSAGING_IGNORE_REQUEST, MESSAGING_PROMOTIONAL_OFF, MESSAGING_READ_RECEIPT, MESSAGING_DELIVERY_RECEIPT, MESSAGING_DELETE_MESSAGE, MESSAGING_CONVERSATION_STARTED_7D, MESSAGING_DEEP_CONVERSATION, MESSAGING_AUTOMATED_FLOW_COMPLETE, MESSAGING_AUTOMATED_FLOW_CANCELLED, MESSENGER_RECEIPT_TEMPLATE, REFERRAL_SENDER_INVITES_SENT, REFERRAL_SENDER_MESSAGE_SENT, REFERRAL_RECEIVER_IMPRESSION, REFERRAL_RECEIVER_CLICK, VIDEO_HOME_SELECTED, VIDEO_HOME_WATCHLIST, VIDEO_HOME_EXPLORE, VIDEO_HOME_PLAYER_START, VIDEO_HOME_90_SECOND_VIEW, FUNDRAISER_CREATE, MESSENGER_CONNECTED_CALL, MESSENGER_MISSED_CALL, D2_RETENTION, D7_RETENTION, MOVIE_SHOWTIME_CLICK, LISTING_INTERACTION, PDP_VIEW, CLICK_TO_CALL, CLICK_TO_WEBSITE, POST_SHARE, OTHER}

pixel_id
Ads Pixel ID

pixel_rule
string

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 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.

time_start
datetime

Time start

time_stop
datetime

Time stop

tune_for_category
enum{NONE, EMPLOYMENT, HOUSING, CREDIT}

tune_for_category

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
801Invalid operation
2625The request for a reach frequency campaign is invalid.
80004There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
294Managing advertisements requires an access token with the extended permission for ads_management
331Your picture is too tall or too wide. Try to pick something closer to a square.
2626The request for a reach frequency campaign has failed.
1150An unknown error occurred.
500Message contains banned content

Deleting

Examples

use FacebookAds\Object\AdSet;

$adset = new AdSet(<AD_SET_ID>);
$adset->deleteSelf();
from facebookads.adobjects.adset import AdSet

adset = AdSet(<AD_SET_ID>)
adset.remote_delete()
new AdSet(<AD_SET_ID>, context).update()
  .setStatus(AdSet.EnumStatus.VALUE_DELETED)
  .execute();
curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_SET_ID>/

You can delete an AdSet by making a DELETE request to /{ad_set_id}.

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
200Permissions error
100Invalid parameter