issues_info list will be populated with one issue per flagged items.curl -X POST \
-F 'name="My Reach Ad Set"' \
-F 'optimization_goal="REACH"' \
-F 'billing_event="IMPRESSIONS"' \
-F 'bid_amount=2' \
-F 'daily_budget=1000' \
-F 'campaign_id="<AD_CAMPAIGN_ID>"' \
-F 'targeting={
"geo_locations": {
"countries": [
"US"
]
},
"facebook_positions": [
"feed"
]
}' \
-F 'status="PAUSED"' \
-F 'promoted_object={
"page_id": "<PAGE_ID>"
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adsets
curl -X POST \
-F 'name="My First Adset"' \
-F 'lifetime_budget=20000' \
-F 'start_time="2025-12-04T20:32:30-0800"' \
-F 'end_time="2025-12-14T20:32:30-0800"' \
-F 'campaign_id="<AD_CAMPAIGN_ID>"' \
-F 'bid_amount=100' \
-F 'billing_event="LINK_CLICKS"' \
-F 'optimization_goal="LINK_CLICKS"' \
-F 'targeting={
"facebook_positions": [
"feed"
],
"geo_locations": {
"countries": [
"US"
]
},
"publisher_platforms": [
"facebook",
"audience_network"
]
}' \
-F 'status="PAUSED"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adsets
| 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 |
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.operation_status of 471, the issues_info list will be populated with one issue per flagged audience as warning.{ "effective_status": "ACTIVE", "issues_info": [ { "level": "AD_SET", "error_code": 2460003, "error_summary": "Custom Audience is blocked", "error_message": "Custom Audience is blocked: Some of this ad set’s custom audiences and/or lookalikes are blocked because they suggest the use of information (e.g., health, financial) not allowed under Meta’s terms. Go to Audience Manager for more details, and you can either review each custom audience or lookalike and remove prohibited information, or choose a different one for your ad set or create a new one and make sure it does not include potentially prohibited information. You can also request a review in Audience Manager if you think any don’t use restricted information.", "error_type": "SOFT_ERROR", "additional_info": "Custom Audience ID: 120231141155310247" }, { "level": "AD_SET", "error_code": 2460003, "error_summary": "Custom Audience is blocked", "error_message": "Custom Audience is blocked: Some of this ad set’s custom audiences and/or lookalikes are blocked because they suggest the use of information (e.g., health, financial) not allowed under Meta’s terms. Go to Audience Manager for more details, and you can either review each custom audience or lookalike and remove prohibited information, or choose a different one for your ad set or create a new one and make sure it does not include potentially prohibited information. You can also request a review in Audience Manager if you think any don’t use restricted information.", "error_type": "SOFT_ERROR", "additional_info": "Custom Audience ID: 120232742978230247" }, { "level": "AD_SET", "error_code": 2460004, "error_summary": "Custom Conversion is blocked", "error_message": "Custom Conversion is blocked: This ad set’s custom conversion is blocked because it suggests the use of information (e.g., health, financial) not allowed under Meta’s terms. You can’t edit this custom conversion, but you can choose a different one for this ad set or create a new one that doesn’t use prohibited information. You can also request a review if you think your custom conversion doesn’t use prohibited information.", "error_type": "SOFT_ERROR", "additional_info": "Custom Conversion ID: 730362226205831" } ], "id": "120228591637010247" }
{ "error": { "error_subcode": 246003, "error_data": { "Restricted Custom Audience IDs": [ "<CUSTOM_AUDIENCE_ID1>", "<CUSTOM_AUDIENCE_ID2>" ] } "error_user_title": "Your custom audience is currently blocked", "error_user_msg": " This custom audience is blocked because it may contain information (e.g., health, financial) not allowed under Meta’s terms. Visit the audience manager to appeal this decision, edit your audience and remove prohibited information, or choose a different audience." }, }
{ "error": { "error_subcode": 246004, "error_data": { "Restricted Custom Conversion ID": "<CUSTOM_CONVERSION_ID>" } "error_user_title": "Your custom conversion is currently blocked", "error_user_msg": "This custom conversion is blocked because it may contain information (e.g., health, financial) not allowed under Meta’s terms. Visit the events manager to appeal this decision, edit your custom conversion and remove prohibited information, or choose a different custom conversion." }, }
default_dsa_payor and default_dsa_beneficiary, see to the check the Ad Account reference document.default_dsa_payor is payor_default and default_dsa_beneficiary is beneficiary_default. During ad set creation, if only dsa_payor is passed with the payor, the dsa_beneficiary will be automatically filled with value of beneficiary_default instead of dsa_payor.payer and the beneficiary fields are only for ad sets targeting the EU and/or associated territories.date_preset = lifetime parameter is disabled in Graph API v10.0 and replaced with date_preset = maximum, which returns a maximum of 37 months of data. For v9.0 and below, date_preset = maximum will be enabled on May 25, 2021, and any lifetime calls will default to maximum and return only 37 months of data.curl -X GET \
-d 'fields="name,status"' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<AD_SET_ID>/
date_format parameter:
curl -X GET \
-d 'fields="id,name,start_time,end_time"' \
-d 'date_format="U"' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<AD_SET_ID>/
GET /v25.0/<AD_SET_ID>/?fields=adset_schedule HTTP/1.1 Host: graph.facebook.com
| Parameter | Description |
|---|---|
date_presetenum{today, yesterday, this_month, last_month, this_quarter, maximum, data_maximum, 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. Note if time range is invalid, it will be ignored.
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.
Show child parameters |
| Field | Description |
|---|---|
idnumeric string |
ID for the Ad Set
default |
account_idnumeric string |
ID for the Ad Account associated with this Ad Set
|
Ad Labels associated with this ad set
| |
adset_schedulelist<DayPart> |
Ad set schedule, representing a delivery schedule for a single day
|
asset_feed_idnumeric string |
The ID of the asset feed that constains a content to create ads
|
attribution_speclist<AttributionSpec> |
Conversion attribution spec used for attributing conversions for optimization. Supported window lengths differ by optimization goal and campaign objective. See Objective, Optimization Goal and attribution_spec.
|
Map of bid adjustment types to values
| |
bid_amountunsigned 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.
|
Choose bid constraints for ad set to suit your specific business goals. It usually works together with bid_strategy field.
| |
bid_infomap<string, unsigned int32> |
Map of bid objective to bid value.
|
bid_strategy enum {LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS} |
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.Notes:
|
billing_eventenum {APP_INSTALLS, CLICKS, IMPRESSIONS, LINK_CLICKS, NONE, OFFER_CLAIMS, PAGE_LIKES, POST_ENGAGEMENT, THRUPLAY, PURCHASE, LISTING_INTERACTION} |
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.
|
brand_safety_configBrandSafetyCampaignConfig |
brand_safety_config
|
budget_remainingnumeric string |
Remaining budget of this Ad Set
|
The campaign that contains this ad set
| |
campaign_active_timenumeric string |
Campaign running length
|
campaign_attributionenum |
campaign_attribution, a new field for app ads campaign, used to indicate a campaign's attribution type, eg: SKAN or AEM
|
campaign_idnumeric string |
The ID of the campaign that contains this ad set
|
configured_statusenum {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.
|
contextual_bundling_specContextualBundlingSpec |
specs of contextual bundling Ad Set setup, including signal of opt-in/out the feature
|
created_timedatetime |
Time when this Ad Set was created
|
creative_sequencelist<numeric string> |
Order of the adgroup sequence to be shown to users
|
daily_budgetnumeric string |
The daily budget of the set defined in your account currency.
|
daily_min_spend_targetnumeric 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_capnumeric 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_typestring |
Destination of ads in this Ad Set.
Options include: WEBSITE, APP, MESSENGER, INSTAGRAM_DIRECT.
The ON_AD, ON_POST, ON_VIDEO, ON_PAGE, and ON_EVENT destination types are currently in limited beta testing. Trying to duplicate campaigns with existing destination types using these new destination types may throw an error. See the Outcome-Driven Ads Experiences section below for more information.
|
dsa_beneficiarystring |
The beneficiary of all ads in this ad set.
|
dsa_payorstring |
The payor of all ads in this ad set.
|
effective_statusenum {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_timedatetime |
End time, in UTC UNIX timestamp
|
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.
| |
instagram_user_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.
|
is_incremental_attribution_enabledbool |
Whether the campaign should use incremental attribution optimization.
|
Issues for this ad set that prevented it from deliverying
| |
Info about whether the ranking or delivery system is still learning for this ad set. While the ad set is still in learning , we might unstablized delivery performances.
| |
lifetime_budgetnumeric string |
The lifetime budget of the set defined in your account currency.
|
lifetime_impsint32 |
Lifetime impressions. Available only for campaigns with buying_type=FIXED_CPM |
lifetime_min_spend_targetnumeric 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_capnumeric 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.
|
min_budget_spend_percentagenumeric string |
min_budget_spend_percentage
|
multi_optimization_goal_weightstring |
multi_optimization_goal_weight
|
namestring |
Name of the ad set
|
optimization_goalenum {NONE, APP_INSTALLS, AD_RECALL_LIFT, ENGAGED_USERS, EVENT_RESPONSES, IMPRESSIONS, LEAD_GENERATION, QUALITY_LEAD, LINK_CLICKS, OFFSITE_CONVERSIONS, PAGE_LIKES, POST_ENGAGEMENT, QUALITY_CALL, REACH, LANDING_PAGE_VIEWS, VISIT_INSTAGRAM_PROFILE, ENGAGED_PAGE_VIEWS, VALUE, THRUPLAY, DERIVED_EVENTS, APP_INSTALLS_AND_OFFSITE_CONVERSIONS, CONVERSATIONS, IN_APP_VALUE, MESSAGING_PURCHASE_CONVERSION, MESSAGING_DEEP_CONVERSATION_AND_FOLLOW, SUBSCRIBERS, REMINDERS_SET, MEANINGFUL_CALL_ATTEMPT, PROFILE_VISIT, PROFILE_AND_PAGE_ENGAGEMENT, ADVERTISER_SILOED_VALUE, AUTOMATIC_OBJECTIVE, MESSAGING_APPOINTMENT_CONVERSION} |
The 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.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.QUALITY_LEAD: Optimize for people who are likely to have a deeper conversation with advertisers after lead submission.LINK_CLICKS: Optimize for people more likely to click in the link of the ad.OFFSITE_CONVERSIONS: Optimize for people more likely to make a conversion on the site.PAGE_LIKES: Optimize for people more likely to like your page.POST_ENGAGEMENT: Optimize for people more likely to engage with your post.QUALITY_CALL: Optimize for people who are likely to call the advertiser.REACH: Optimize to reach the most unique users for each day or interval specified in frequency_control_specs.LANDING_PAGE_VIEWS: Optimize for people who are most likely to click on and load your chosen landing page.VISIT_INSTAGRAM_PROFILE: Optimize for visits to the advertiser's Instagram profile.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.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.APP_INSTALLS_AND_OFFSITE_CONVERSIONS: Optimizes for people more likely to install your app and make a conversion on your site. CONVERSATIONS: Directs ads to people more likely to have a conversation with the business.
|
optimization_sub_eventstring |
Optimization sub event for a specific optimization goal. For example: Sound-On event for Video-View-2s optimization goal.
|
pacing_typelist<string> |
Defines the pacing type, standard or using ad scheduling
|
The object this ad set is promoting across all its ads.
| |
recommendationslist<AdRecommendation> |
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_semanticsbool |
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.
|
regional_regulated_categorieslist<enum> |
This param is used to specify regional_regulated_categories. Currently it supports null and the following values:
If an ad set is a Financial Service Ad and it targets Taiwan, it needs to declare both TAIWAN_FINSERV and TAIWAN_UNIVERSAL
Example: null or [AUSTRALIA_FINSERV] or [TAIWAN_FINSERV, TAIWAN_UNIVERSAL] |
regional_regulation_identitiesRegionalRegulationIdentities |
This param is used to specify regional_regulation_identities used to represent the ad set. Currently it supports the following fields:
Example:
regional_regulation_identities: {
"taiwan_finserv_beneficiary": <verified_identity_id>,
"taiwan_finserv_payer": <verified_identity_id>,
"taiwan_universal_beneficiary": <verified_identity_id>,
"taiwan_universal_payer": <verified_identity_id>,
}
During creation and update, the passed identities fields need to correspond to declared categories. Both beneficiary and payer identities must be included, and they can use the same identity ID.
To update an existing ad set identities, you need to pass new values for both categories and identities to overwrite the identity id or null to remove existing id.
For example:
Upon creation, regional_regulated_categories is [TAIWAN_FINSERV, TAIWAN_UNIVERSAL] and regional_regulation_identities is
regional_regulation_identities: {
"taiwan_finserv_beneficiary": <id_123>,
"taiwan_finserv_payer": <id_123>,
"taiwan_universal_beneficiary": <id_456>,
"taiwan_universal_payer": <id_456>,
}
For update, passing [TAIWAN_UNIVERSAL] and
regional_regulation_identities: {
"taiwan_finserv_beneficiary": null
"taiwan_finserv_payer": null,
"taiwan_universal_beneficiary": <id_789>,
"taiwan_universal_payer": <id_789>,
}
will remove TAIWAN_FINSERV declaration and update the identities ID of TAIWAN_UNIVERSAL |
review_feedbackstring |
Reviews for dynamic creative ad
|
rf_prediction_idid |
Reach and frequency prediction ID
|
The source ad set that this ad set was copied from
| |
source_adset_idnumeric string |
The source ad set id that this ad set was copied from
|
start_timedatetime |
Start time, in UTC UNIX timestamp
|
statusenum {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.
|
targetingTargeting |
Targeting
|
targeting_optimization_types list<KeyValue:string,int32> |
Targeting options that are relaxed and used as a signal for optimization
|
time_based_ad_rotation_id_blockslist<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_intervalslist<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_timedatetime |
Time when the Ad Set was updated
|
use_new_app_clickbool |
If set, allows Mobile App Engagement ads to optimize for LINK_CLICKS
|
value_rule_set_idnumeric string |
value_rule_set_id
|
| Edge | Description |
|---|---|
activitiesEdge<AdActivity> |
The activities of this ad set
|
ad_studiesEdge<AdStudy> |
The ad studies containing this ad set
|
adcreativesEdge<AdCreative> |
The creatives of this ad set
|
adrules_governedEdge<AdRule> |
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 |
adsEdge<Adgroup> |
The ads under this ad set
|
asyncadrequestsEdge<AdAsyncRequest> |
Async ad requests for this ad set
|
copiesEdge<AdCampaign> |
The copies of this ad set
|
delivery_estimateEdge<AdCampaignDeliveryEstimate> |
The delivery estimate for this ad set
|
message_delivery_estimateEdge<MessageDeliveryEstimate> |
Delivery estimation of the marketing message campaign
|
targetingsentencelinesEdge<TargetingSentenceLine> |
The targeting description sentence for this ad set
|
| Error Code | Description |
|---|---|
2635 | You are calling a deprecated version of the Ads API. Please update to the latest version. |
100 | Invalid parameter |
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. |
190 | Invalid OAuth 2.0 Access Token |
200 | Permissions error |
2500 | Error parsing graph query |
ON_POST destination_type.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/v25.0/act_<AD_ACCOUNT_ID>/adsets
bid_strategy is set to LOWEST_COST_WITHOUT_CAP in the ad set:
| Billing Event | Minimum Daily Budget |
|---|---|
Impressions | $0.50 |
Clicks/Likes/Video Views | $2.50 |
Low-frequency Actions (Includes mobile app installs, offer claims, or canvas app installs) | $40 Important: This minimum daily budget is the same for all countries. |
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. |
bid_strategy is LOWEST_COST_WITHOUT_CAP.
user_device and user_osMOBILE_APP_* objective on the campaign'page_types':['desktopfeed'] or
'page_types':['rightcolumn'] or
'page_types':['desktop'] along with the other targeting options you have selected.
CANVAS_APP_* objective
targeting_optimization_types map that indicates lookalike expansion is enabled and complements the existing detailed_targeting property for the detailed targeting expansion.
dsa_payor and dsa_beneficiary fields are required. The information provided in these 2 fields will be shown to end users to indicate who is paying for the ad and who is the beneficiary of the ad.
/{adset_id} endpoint.
{
"dsa_payor": "<PAYOR_NAME>",
"dsa_beneficiary": "<BENEFICIARY_NAME>"
...
}
| Name | Description |
|---|---|
dsa_payor
string (max 512 char)
| The payor of all ads in this ad set. |
dsa_beneficiary
string (max 512 char)
| The beneficiary of all ads in this ad set. |
{
"error": {
"message": "Invalid parameter",
"type": "FacebookApiException",
"code": 100,
"error_data": "{\"blame_field_specs\":[[\"dsa_payor\"]]}",
"error_subcode": 3858079,
"is_transient": false,
"error_user_title": "No payor provided in DSA regulated region",
"error_user_msg": "The DSA requires ads to provide payor information in regulated regions. Updating/creating ad needs to provide payor of the ad.",
"fbtrace_id": "fbtrace_id"
},
"__fb_trace_id__": "fbtrace_id",
"__www_request_id__": "request_id"
}
{
"error": {
"message": "Invalid parameter",
"type": "FacebookApiException",
"code": 100,
"error_data": "{\"blame_field_specs\":[[\"dsa_beneficiary\"]]}",
"error_subcode": 3858081,
"is_transient": false,
"error_user_title": "No payor/beneficiary provided in DSA regulated location",
"error_user_msg": "The DSA requires ads to provide beneficiary information in regulated regions. Updating/creating ad needs to provide beneficiary of the ad.",
"fbtrace_id": "fbtrace_id"
},
"__fb_trace_id__": "fbtrace_id",
"__www_request_id__": "request_id"
}
| Parameter | Description |
|---|---|
campaign_idnumeric 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_copyboolean | 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_timedatetime |
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_optionsJSON or object-like arrays |
Rename options
rename_strategy enum {DEEP_RENAME, ONLY_TOP_LEVEL_RENAME, NO_RENAME}Default value: ONLY_TOP_LEVEL_RENAMEDEEP_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.
Show child parameters |
start_timedatetime |
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_optionenum {ACTIVE, PAUSED, INHERITED_FROM_SOURCE} | Default value: PAUSEDACTIVE: 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.
|
Struct {
copied_adset_id: numeric string,
ad_object_ids: List [ Struct {
ad_object_type: enum {
unique_adcreative,
ad,
ad_set,
campaign,
opportunities,
privacy_info_center,
topline,
ad_account,
product},
source_id: numeric string,
copied_id: numeric string,
}],
}
| Error Code | Description |
|---|---|
100 | Invalid parameter |
200 | Permissions error |
190 | Invalid OAuth 2.0 Access Token |
2695 | The ad set creation reached its campaign group(ios14) limit. |
2635 | You are calling a deprecated version of the Ads API. Please update to the latest version. |
POST /v25.0/act_<AD_ACCOUNT_ID>/adsets HTTP/1.1 Host: graph.facebook.com name=My+First+Adset&lifetime_budget=20000&start_time=2026-05-12T10%3A45%3A09-0700&end_time=2026-05-22T10%3A45%3A09-0700&campaign_id=%3CAD_CAMPAIGN_ID%3E&bid_amount=100&billing_event=LINK_CLICKS&optimization_goal=LINK_CLICKS&targeting=%7B%22facebook_positions%22%3A%5B%22feed%22%5D%2C%22geo_locations%22%3A%7B%22countries%22%3A%5B%22US%22%5D%7D%2C%22publisher_platforms%22%3A%5B%22facebook%22%2C%22audience_network%22%5D%7D&status=PAUSED
| Parameter | Description |
|---|---|
adlabelslist<Object> |
Specifies list of labels to be associated with this object. This field is optional
|
adset_schedulelist<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: USERShow child parameters |
attribution_speclist<JSON object> |
Conversion attribution spec used for attributing conversions for optimization. Supported window lengths differ by optimization goal and campaign objective.
event_type enum {CLICK_THROUGH, VIEW_THROUGH, ENGAGED_VIDEO_VIEW}required window_days int64required weight floatDefault value: 100Show child parameters |
automatic_manual_stateenum{UNSET, AUTOMATIC, MANUAL} |
automatic_manual_state
|
bid_amountinteger |
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:
|
billing_eventenum{APP_INSTALLS, CLICKS, IMPRESSIONS, LINK_CLICKS, NONE, OFFER_CLAIMS, PAGE_LIKES, POST_ENGAGEMENT, THRUPLAY, PURCHASE, LISTING_INTERACTION} |
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. |
budget_schedule_specslist<JSON or object-like arrays> |
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. id int64time_start datetimetime_end datetimebudget_value int64budget_value_type enum{ABSOLUTE, MULTIPLIER}recurrence_type enum{ONE_TIME, WEEKLY}weekly_schedule list<JSON or object-like arrays>days list<int64>minute_start int64minute_end int64timezone_type stringShow child parameters Show child parameters |
budget_sourceenum{NONE, RMN} |
budget_source
|
budget_split_set_idnumeric string or integer |
budget_split_set_id
|
campaign_attributionenum{} |
campaign_attribution
|
campaign_idnumeric string or integer |
The ad campaign you wish to add this ad set to.
|
campaign_specCampaign 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" }' Please refer to the Outcome-Driven Ads Experiences mapping table to find new objectives and their corresponding destination types, optimization goals and promoted objects. |
contextual_bundling_specObject |
settings of Contextual Bundle to support ads serving in Facebook contextual surfaces
status enum{OPT_OUT, OPT_IN}Show child parameters |
cost_bidding_modeenum{VOLUME_FOCUSED, BALANCED, COST_FOCUSED} |
cost_bidding_mode
|
creative_sequencelist<numeric string or integer> |
Order of the adgroup sequence to be shown to users
|
daily_budgetint64 |
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_impsint64 |
Daily impressions. Available only for campaigns with buying_type=FIXED_CPM |
daily_min_spend_targetint64 |
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_capint64 |
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_typeenum{WEBSITE, APP, MESSENGER, APPLINKS_AUTOMATIC, WHATSAPP, INSTAGRAM_DIRECT, FACEBOOK, MESSAGING_MESSENGER_WHATSAPP, MESSAGING_INSTAGRAM_DIRECT_MESSENGER, MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP, MESSAGING_INSTAGRAM_DIRECT_WHATSAPP, SHOP_AUTOMATIC, ON_AD, ON_POST, ON_EVENT, ON_VIDEO, ON_PAGE, INSTAGRAM_PROFILE, FACEBOOK_PAGE, INSTAGRAM_PROFILE_AND_FACEBOOK_PAGE, INSTAGRAM_LIVE, FACEBOOK_LIVE, IMAGINE} |
Destination of ads in this Ad Set. Options include: Website, App, Messenger, INSTAGRAM_DIRECT, INSTAGRAM_PROFILE.
|
dsa_beneficiarystring |
dsa_beneficiary
|
dsa_payorstring |
dsa_payor
|
end_timedatetime |
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_optionslist<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.
|
existing_customer_budget_percentageint64 |
existing_customer_budget_percentage
|
frequency_control_specslist<Object> |
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.
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 type enum{NONE, CAP, TARGET}Show child parameters |
is_dc_follow_optimizedboolean |
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_certifiedboolean |
is_sac_cfca_terms_certified
|
lifetime_budgetint64 |
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_impsint64 |
Lifetime impressions. Available only for campaigns with buying_type=FIXED_CPM |
lifetime_min_spend_targetint64 |
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_capint64 |
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_percentageint64 |
max_budget_spend_percentage
|
min_budget_spend_percentageint64 |
min_budget_spend_percentage
|
multi_event_conversion_attribution_window_secondsint64 |
multi_event_conversion_attribution_window_seconds
|
multi_optimization_goal_weightenum{UNDEFINED, BALANCED, PREFER_INSTALL, PREFER_EVENT} |
multi_optimization_goal_weight
|
namestring |
Ad set name, max length of 400 characters.
required supports emoji |
optimization_goalenum{NONE, APP_INSTALLS, AD_RECALL_LIFT, ENGAGED_USERS, EVENT_RESPONSES, IMPRESSIONS, LEAD_GENERATION, QUALITY_LEAD, LINK_CLICKS, OFFSITE_CONVERSIONS, PAGE_LIKES, POST_ENGAGEMENT, QUALITY_CALL, REACH, LANDING_PAGE_VIEWS, VISIT_INSTAGRAM_PROFILE, ENGAGED_PAGE_VIEWS, VALUE, THRUPLAY, DERIVED_EVENTS, APP_INSTALLS_AND_OFFSITE_CONVERSIONS, CONVERSATIONS, IN_APP_VALUE, MESSAGING_PURCHASE_CONVERSION, MESSAGING_DEEP_CONVERSATION_AND_FOLLOW, SUBSCRIBERS, REMINDERS_SET, MEANINGFUL_CALL_ATTEMPT, PROFILE_VISIT, PROFILE_AND_PAGE_ENGAGEMENT, ADVERTISER_SILOED_VALUE, AUTOMATIC_OBJECTIVE, MESSAGING_APPOINTMENT_CONVERSION} |
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 sitePAGE_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_eventenum{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, POST_INTERACTION} |
Optimization sub event for a specific optimization goal (ex: Sound-On event for Video-View-2s optimization goal)
|
pacing_typelist<string> |
Defines the pacing type, standard by default or using ad scheduling |
promoted_objectObject |
The object this ad set is promoting across all its ads.
Required with certain campaign objectives. CONVERSIONS
optimization_goal is OFFSITE_CONVERSIONS
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. 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{AD_IMPRESSION, 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.
object_store_urls list<URL>
The vec of 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.
job_listing_id numeric string or integer
The ID of the marketplace job listing.
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.
mcme_conversion_id numeric string or integer
The ID of a MCME conversion.
conversion_goal_id numeric string or integer
The ID of a Conversion Goal.
offsite_conversion_event_id numeric string or integer
The ID of a Offsite Conversion Event
boosted_product_set_id numeric string or integer
The ID of the Boosted Product Set within an Ad Set level Product
Catalog. Should only be present when the advertiser has
opted into Product Set Boosting.
lead_ads_form_event_source_type enum{inferred, meta_source, offsite_crm, offsite_web, onsite_crm, onsite_crm_single_event, onsite_clo_dep_aet, onsite_web, onsite_p2b_call, onsite_messaging, qualified_lead_file}
The event source of lead ads form.
lead_ads_custom_event_type enum{AD_IMPRESSION, 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.
lead_ads_custom_event_str string
The event from an App Event of a mobile app,
not in the standard event list.
lead_ads_offsite_conversion_type enum{default, clo}
The offsite conversion type for lead ads
value_semantic_type enum {VALUE, MARGIN, LIFETIME_VALUE}
The semantic of the event value to be using for optimization
variation enum {OMNI_CHANNEL_SHOP_AUTOMATIC_DATA_COLLECTION, PRODUCT_SET_AND_APP, PRODUCT_SET_AND_IN_STORE, PRODUCT_SET_AND_OMNICHANNEL, PRODUCT_SET_AND_PHONE_CALL, PRODUCT_SET_AND_WEBSITE, PRODUCT_SET_AND_WEBSITE_AND_PHONE_CALL, PRODUCT_SET_WEBSITE_APP_AND_INSTORE}
Variation of the promoted object for a PCA ad
passback_pixel_id numeric string or integer
ID of the pixel used for tracking passback events
passback_application_id numeric string or integer
ID of the application used for tracking passback events
product_set_optimization enum{enabled, disabled}
Enum defining whether or not the ad should be optimized for the promoted product set
full_funnel_objective enum{OFFER_CLAIMS, PAGE_LIKES, EVENT_RESPONSES, POST_ENGAGEMENT, WEBSITE_CONVERSIONS, LINK_CLICKS, VIDEO_VIEWS, LOCAL_AWARENESS, PRODUCT_CATALOG_SALES, LEAD_GENERATION, BRAND_AWARENESS, STORE_VISITS, REACH, APP_INSTALLS, MESSAGES, OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_TRAFFIC, OUTCOME_APP_PROMOTION}
Enum defining the full funnel objective of the campaign
dataset_split_id numeric string or integer
ID of the dataset split used to perform additional optimization on the dataset
dataset_split_ids array<numeric string>
IDs of the dataset splits used to perform additional optimization on the dataset
lead_ads_selected_pixel_id numeric string or integer
The selected pixel id for lead ads conversion leads optimization
custom_attribution_source_ids array<numeric string>
IDs of the custom attribution sources used for tracking passback events
multi_event_product int64
Identifies which action-to-action product the advertiser is using
product_sales_channel enum {ONLINE, IN_STORE, OMNI}
ProductSalesChannel of the promoted object for Omni L3 DA SBLI ads
anchor_event_config JSON object
Configuration for anchor event in multi-event optimization campaigns
multi_event_conversion_info JSON object
Configuration for multi-event conversion info in CLO campaigns
live_video_destination string
The live video destination type for live video ads
smart_pse_enabled boolean
Whether Smart Product Set Expansion is enabled for this campaign.
smart_pse_setting enum{ENABLED, DISABLED}
Setting for Smart Product Set Expansion. Uses an enum instead of a boolean to avoid TAO null handling issues.
lead_ads_follow_up_event enum{whatsapp_conversations}
The selected lead follow-up event for lead ads campaigns.
omnichannel_object Objectapp array<JSON object>pixel array<JSON object>required onsite array<JSON object>Show child parameters whats_app_business_phone_number_id numeric string or integerwhatsapp_phone_number stringShow child parameters |
relative_valuefloat |
relative_value
|
rf_prediction_idnumeric string or integer |
Reach and frequency prediction ID
|
source_adset_idnumeric string or integer |
The source adset id that this ad is copied from (if applicable).
|
start_timedatetime |
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
|
statusenum{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.
|
targetingTargeting object |
An ad set's targeting structure. "countries" is required. See targeting.
|
time_based_ad_rotation_id_blockslist<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_intervalslist<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_startdatetime |
Time start
|
time_stopdatetime |
Time stop
|
tune_for_categoryenum{NONE, EMPLOYMENT, HOUSING, CREDIT, ISSUES_ELECTIONS_POLITICS, ONLINE_GAMBLING_AND_GAMING, FINANCIAL_PRODUCTS_SERVICES} |
tune_for_category
|
value_rule_set_idnumeric string or integer |
Value Rule Set ID
|
value_rules_appliedboolean |
value_rules_applied
|
Struct {
id: numeric string,
success: bool,
}
| Error Code | Description |
|---|---|
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. |
curl -X POST \
-F 'billing_event="IMPRESSIONS"' \
-F 'optimization_goal="LINK_CLICKS"' \
-F 'bid_amount=200' \
-F 'targeting={
"geo_locations": {
"countries": [
"US"
]
},
"facebook_positions": [
"feed"
]
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<AD_SET_ID>/
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();
use FacebookAds\Object\AdSet;
$adset = new AdSet('<AD_SET_ID>');
$adset->campaign_status = AdSet::STATUS_PAUSED;
$adset->update();
name and campaign_status. The campaign_status field can only be changed to DELETED.
name.
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.
curl -X DELETE \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<AD_SET_ID>/
DELETE /v25.0/<AD_SET_ID>/ HTTP/1.1 Host: graph.facebook.com
Struct {
success: bool,
}
| Error Code | Description |
|---|---|
200 | Permissions error |
100 | Invalid parameter |
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. |
ON_PAGE destination_type)
curl -i -X POST \
-d "name=New ODAX Adset" \
-d "autobid=true" \
-d "optimization_goal=PAGE_LIKES" \
-d "destination_type=ON_PAGE" \
-d "billing_event=IMPRESSIONS" \
-d "daily_budget=500" \
-d "targeting={\"geo_locations\": {\"countries\": [\"US\"]}}" \
-d "promoted_object={\"page_id\": PAGE_ID}" \
-d "campaign_id=CAMPAIGN_ID" \
-d "status=PAUSED" \
-d "access_token=ACCESS_TOKEN" \
https://graph.facebook.com/v11.0/
act_AD_ACCOUNT_ID/adsets

curl -i -X POST \
-d "name=New ODAX Adset" \
-d "autobid=true" \
-d "optimization_goal=PAGE_LIKES" \
-d "billing_event=IMPRESSIONS" \
-d "daily_budget=500" \
-d "targeting={\"geo_locations\": {\"countries\": [\"US\"]}}" \
-d "promoted_object={\"page_id\": PAGE_ID}" \
-d "campaign_id=CAMPAIGN_ID" \
-d "status=PAUSED" \
-d "access_token=ACCESS_TOKEN" \
https://graph.facebook.com/v11.0/
act_AD_ACCOUNT_ID/adsets
| ODAX Objectives | Conversion Location (L2) | Conversion Events (L2) | Optimization Goals (L2) | Legacy Objectives |
|---|---|---|---|---|
Awareness Reach the largest number of people who are likely to remember your ad. | N/A | N/A | Ad Recall Lift, Reach, Impressions
API enum { AD_RECALL_LIFT, REACH, IMPRESSIONS} | Reach, Brand Awareness |
Traffic Send people to a destination like your website, app or Shop. | Facebook Shops (closed beta) | N/A | Link Clicks
API enum { LINK_CLICKS} | Traffic |
Website | N/A | Landing Page Views, Link Clicks, Impressions, Daily Unique Reach
API enum { LANDING_PAGE_VIEWS, LINK_CLICKS, IMPRESSIONS, REACH} | Traffic | |
App | N/A | Link Clicks, Daily Unique Reach
API enum { LINK_CLICKS, REACH} | Traffic | |
Messenger | N/A | Link Clicks, Impressions, Daily Unique Reach
API enum { LINK_CLICKS, IMPRESSIONS, REACH} | Traffic | |
WhatsApp | N/A | Link Clicks, Impressions, Daily Unique Reach
API enum { LINK_CLICKS, IMPRESSIONS, REACH} | Traffic | |
Engagement Find people likely to interact with your business online, and take actions like starting a conversation or commenting on posts. | On Video | N/A | ThruPlay, 2 second continuous view
API enum { THRUPLAY, TWO_SECOND_CONTINUOUS_VIDEO_VIEWS} | Video Views |
On Post | N/A | Post Engagement, Impressions, Daily Unique Reach
API enum { POST_ENGAGEMENT, IMPRESSIONS, REACH} | Post Engagement | |
On Event | N/A | Event Response, Impressions, Post Engagement, Daily Unique Reach
API enum { EVENT_RESPONSES, IMPRESSIONS, POST_ENGAGEMENT, REACH} | Event Responses | |
Messenger | N/A | Conversations, Link Clicks
API enum { CONVERSATIONS, LINK_CLICKS} | Messages | |
WhatsApp | N/A | Conversations, Link Clicks
API enum { CONVERSATIONS, LINK_CLICKS} | Messages | |
Instagram | N/A | Conversations, Link Clicks
API enum { CONVERSATIONS, LINK_CLICKS} | Messages | |
Website | AddToWishlist, Contact, CustomizeProduct, Donate, FindLocation,, Schedule, Search, StartTrial, SubmitApplication, Subscribe, ViewContent | Conversions, Landing Page Views, Link Clicks, Impressions, Daily Unique Reach
API enum { OFFSITE_CONVERSIONS, ONSITE_CONVERSIONS, LANDING_PAGE_VIEWS, LINK_CLICKS, IMPRESSIONS, REACH} | Conversions | |
App | Achieve Level, Activate App, Add to Wishlist, Complete Tutorial, Contact, Customize Product, Donate, Find Location, In-App Ad Click, In-App Ad Impression, Rate, Schedule, Search, Spent Credits, Start Trial, Submit Application, Subscribe, Unlock Achievement, View Content | App Events, Link Clicks, Daily Unique Reach
API enum { APP_INSTALLS_AND_OFFSITE_CONVERSIONS, LINK_CLICKS, REACH} | Conversions | |
On Page | N/A | Page Likes
API enum { PAGE_LIKES} | Engagement | |
Leads Find people interested in your business who are likely to share their contact information. | Website | Lead, CompleteRegistration, Contact, FindLocation, Schedule, StartTrial, SubmitApplication, Subscribe | Conversions, Landing Page Views, Link Clicks, Impressions, Daily Unique Reach
API enum { OFFSITE_CONVERSIONS, ONSITE_CONVERSIONS, LANDING_PAGE_VIEWS, LINK_CLICKS, IMPRESSIONS, REACH} | Conversions |
Instant Forms | N/A | Leads
API enum { LEAD_GENERATION, QUALITY_LEAD} | Lead Generation | |
Messenger | N/A | Leads
API enum { LEAD_GENERATION, QUALITY_LEAD} | Messages | |
Calls | N/A | Calls
API enum { QUALITY_CALL} | Lead Generation | |
App | Complete Registration, Complete Tutorial, Contact, Find Location, Schedule, Start Trial, Submit Application, Subscribe | App Events, Link Clicks, Daily Unique Reach
API enum { APP_INSTALLS_AND_OFFSITE_CONVERSIONS, LINK_CLICKS, REACH} | Conversions | |
App Promotion Find people likely to install your app. | N/A | All app events, including all custom events | Non-AAA: Link Clicks, App Installs, App Events, Value
API enum { LINK_CLICKS, APP_INSTALLS, APP_INSTALLS_AND_OFFSITE_CONVERSIONS, VALUE}
AAA: App Installs, App Installs w/ App Events, App Events, Value API enum { APP_INSTALLS, APP_INSTALLS_AND_OFFSITE_CONVERSIONS, VALUE} | App Installs |
Sales Find people likely to make purchases or take other important actions online or in store. | Website & Facebook Shops (closed beta) | Purchase, InitiateCheckout, AddPaymentInfo, AddToCart, CompleteRegistration, Donate, StartTrial, Subscribe, ViewContent | (source of truth: same as today’s Conversions objective + web and shop)
API enum { OFFSITE_CONVERSIONS, VALUE, LINK_CLICKS, LANDING_PAGE_VIEWS, LINK_CLICKS, IMPRESSIONS, REACH} | Conversions |
Website | Purchase, InitiateCheckout, AddPaymentInfo, AddToCart, CompleteRegistration, Donate, StartTrial, Subscribe, ViewContent | Conversions, Value, Landing Page Views, Link Clicks, Impressions, Daily Unique Reach
API enum { OFFSITE_CONVERSIONS, VALUE, LANDING_PAGE_VIEWS, LINK_CLICKS, IMPRESSIONS, REACH} | Conversions | |
App | Purchase, Initiate Checkout, Add Payment Info, Add to Cart, Complete Registration, Donate, In-App Ad Click, In-App Ad Impression, Spent Credits, Start Trial, Subscribe, View Content | App Events, Link Clicks, Daily Unique Reach
API enum { OFFSITE_CONVERSIONS, LINK_CLICKS, REACH} | Conversions | |
Website & App | Purchase, InitiateCheckout, AddPaymentInfo, AddToCart, CompleteRegistration, Donate, StartTrial, Subscribe, ViewContent | Conversions
API enum { OFFSITE_CONVERSIONS} | Conversions | |
Messenger | Purchase, InitiateCheckout, AddPaymentInfo, AddToCart, CompleteRegistration, Donate, StartTrial, Subscribe, ViewContent | Conversations, Conversions, Link Clicks, Impressions, Reach
API enum { CONVERSATIONS, OFFSITE_CONVERSIONS, LINK_CLICKS, IMPRESSIONS, REACH} | Conversions | |
WhatsApp | Purchase, InitiateCheckout, AddPaymentInfo, AddToCart, CompleteRegistration, Donate, StartTrial, Subscribe, ViewContent | Conversions, Link Clicks, Impressions, Reach
API enum { OFFSITE_CONVERSIONS, LINK_CLICKS, IMPRESSIONS, REACH} | Conversions |