Ad Account Adsets

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

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

Conversion attribution spec used for attributing conversions for optimization. Supported window lengths differ by optimization goal and campaign objective.

automatic_manual_state

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 or 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, COST_CAP, LOWEST_COST_WITH_MIN_ROAS}

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

Notes:

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.

Initial high demand periods to be created with the ad set.
Provide list of time_start, time_end,budget_value, and budget_value_type.
For example,
-F 'budget_schedule_specs=[{
"time_start":1699081200,
"time_end":1699167600,
"budget_value":100,
"budget_value_type":"ABSOLUTE"
}]'
See High Demand Period for more details on each field.

budget_source

budget_split_set_id

campaign_attribution

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

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"
}'

Please refer to the Outcome-Driven Ads Experiences mapping table to find new objectives and their corresponding destination types, optimization goals and promoted objects.

settings of Contextual Bundle to support ads serving in Facebook contextual surfaces

cost_bidding_mode

Order of the adgroup sequence to be shown to users

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 impressions. Available only for campaigns with buying_type=FIXED_CPM

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 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 of ads in this Ad Set. Options include: Website, App, Messenger, INSTAGRAM_DIRECT, INSTAGRAM_PROFILE.

dsa_beneficiary

dsa_payor

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

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.

existing_customer_budget_percentage

An array of frequency control specs for this ad set. Writes to this field are only available in ad sets where REACH and THRUPLAY are the performance goal.

is_dc_follow_optimized

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

is_sac_cfca_terms_certified

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 impressions. Available only for campaigns with buying_type=FIXED_CPM

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

max_budget_spend_percentage

min_budget_spend_percentage

multi_event_conversion_attribution_window_seconds

multi_optimization_goal_weight

Ad set name, max length of 400 characters.

What the ad set is optimizing for.
APP_INSTALLS: Will optimize for people more likely to install your app.
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. For example, 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.
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.
AD_RECALL_LIFT: Optimize for people more likely to remember seeing your ads.
VISIT_INSTAGRAM_PROFILE: Optimize for visits to the advertiser's instagram profile.

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

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

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

if the optimization_goal is OFFSITE_CONVERSIONS

• application_id, object_store_url, and custom_event_type (Standard Events)
• application_id, object_store_url, custom_event_type = OTHER and custom_event_str (Custom Events)

PRODUCT_CATALOG_SALES

• product_set_id
• product_set_id and custom_event_type

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

Please refer to the Outcome-Driven Ads Experiences mapping table to find new objectives and their corresponding destination types, optimization goals and promoted objects.

relative_value

Reach and frequency prediction ID

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

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

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.

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

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.

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

Time stop

tune_for_category

Value Rule Set ID

value_rules_applied

100

Invalid parameter

200

Permissions error

2635

You are calling a deprecated version of the Ads API. Please update to the latest version.

368

The action attempted has been deemed abusive or is otherwise disallowed

2695

The ad set creation reached its campaign group(ios14) limit.

80004

There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to /docs/graph-api/overview/rate-limiting#ads-management.

2641

Your ad includes or excludes locations that are currently restricted

190

Invalid OAuth 2.0 Access Token

900

No such application exists.