Marketing API Version

Ad Account Adsets

Reading

The adsets of this ad account

Example

Graph API Explorer
GET /v2.11/{ad-account-id}/adsets 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-account-id}/adsets',
    '{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-account-id}/adsets",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{ad-account-id}/adsets",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{ad-account-id}/adsets"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
Permissions are not usually requested.
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
ad_draft_id
numeric string

If draft id is specified, adsets from the draft will be included

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}

Predefine date range used to aggregate insights metrics

effective_status
list<enum{ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED}>

Effective status of adset

include_deleted
boolean

Filter adset by deleted status

is_completed
boolean
Default value: true

Filter adset by completed status

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

Date range used to aggregate insights metrics

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

Reading from this edge will return a JSON formatted result:

{ "data": [], "paging": {}, "summary": {} }

data

A list of AdSet nodes.

paging

For more details about pagination, see the Graph API guide.

summary

Aggregated information about the edge, such as counts. Specify the fields to fetch in the summary param (like summary=insights).

FieldDescription

insights

Analytics summary for all objects

total_count

unsigned int32

Total number of objects

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API
273This Ads API call requires the user to be admin of the ad account

Creating

Example

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

Parameters

NameDescription
adlabels
list<Object>

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

adset_schedule
list<Object>

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

start_minute
int64

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

Required
end_minute
int64

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

Required
days
list<int64>

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

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

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

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

campaign_id
numeric string or integer

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

campaign_spec
Campaign spec

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

creative_sequence
list<numeric string or integer>

Order of the adgroup sequence to be shown to users

daily_budget
int64

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

daily_imps
int64

Daily impressions. Available only for campaigns with buying_type=FIXED_CPM

end_time
datetime

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

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

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

frequency_control_specs
list<Object>

An array of frequency control specs for this ad set. As there is only one event type currently supported, this array has no more than one element. Only available in ad sets where REACH is the objective. Cannot be used in Reach & Frequency campaigns.

event
enum{IMPRESSIONS, VIDEO_VIEWS, VIDEO_VIEWS_2S}

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

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

is_average_price_pacing
boolean

Flag used to determine whether average price pacing is enabled. Default value is false. More details can be found in this help document.

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

name
string

Ad set name, max length of 400 characters.

Required
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, LANDING_PAGE_VIEWS, REPLIES}

What the ad set is optimizing for.
APP_INSTALLS: Will optimize for people more likely to install your app.
AD_RECALL_LIFT: Optimize for people more likely to remember seeing your ads. You cannot set bid_amount, and is_autobid must be true if this goal is used.
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 for people more likely to watch videos.

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

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

pixel_id
numeric string or integer

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

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

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

object_store_url
URL

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

offer_id
numeric string or integer

The ID of an Offer from a Facebook Page.

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

redownload
boolean

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

rf_prediction_id
numeric string or integer

Reach and frequency prediction ID

start_time
datetime

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

status
enum{ACTIVE, PAUSED, DELETED, ARCHIVED}

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

targeting
Targeting object

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

time_based_ad_rotation_id_blocks
list<list<int64>>

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

time_based_ad_rotation_intervals
list<int64>

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

Return Type

Struct {
id: numeric string,
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
105The number of parameters exceeded the maximum for this operation
900No such application exists.
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API
2625The request for a reach frequency campaign is invalid.
272This Ads API call requires the user to be admin of the application
273This Ads API call requires the user to be admin of the ad account

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.