Deliver ads on specific placements, such as desktop Feed only or mobile Feed plus Audience Network Rewarded Video. You can only use certain placement options depending on your campaign objective. See Campaign, Objective and Placements for more information.
The platforms and positions available are device_platforms
, publisher_platforms
, facebook_positions
, audience_network_positions
, instagram_positions
and messenger_positions
. See the Device, Publisher and Positions section for more information.
curl -X POST \
-F 'name="My AdSet"' \
-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"
]
},
"publisher_platforms": [
"facebook"
],
"facebook_positions": [
"feed"
]
}' \
-F 'promoted_object={
"page_id": "<PAGE_ID>"
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/adsets
If you do not specify anything for a particular placement field, Facebook considers all possible default positions for that field. For example, if you set publisher_platforms
to facebook
, but select nothing for facebook_positions
, Facebook considers all default Facebook positions such as feed
, right_hand_column
, etc. Or, if you do not select any publisher_platforms
, Facebook considers all default publisher_platforms
. Facebook may also automatically consider new positions or platforms as they become available.
On Audience Network, you can limit which publishers display your ads. Exclude publishers by category, or create a custom list of app store URLs or domain URLs to exclude.
You cannot use only right_hand_column
alone as a placement for video, collection or canvas ads.
Inventory Filter helps you control whether your ads display next to different types of content for in-content ads (Facebook in-stream videos, ads on Facebook Reels and ads on Instagram Reels), Audience Network ads and feed ads (Facebook Feed, Instagram Feed, Facebook Reels Feed and Instagram Reels Feed). To learn more about these content categories, see Ads Help Center, Inventory Filter. You can choose separate values for in-content, Audience Network, and feed ads. Options include: Expanded
, Moderate
, and Limited
. For details, see brand_safety_content_filter_levels
below:
Name | Description |
---|---|
array<string> | For in-content ads (Facebook in-stream and ads on Facebook Reels), we allow these values:
For Audience Network, we allow these values:
For Feed ads (Facebook Feed, Instagram Feed, Facebook Reels Feed and Instagram Reels Feed), we allow these values:
Example: Note: When a filter is applied at the ad account level, only more restrictive options will be available at the campaign level. For example, if the account is set to |
array<string> | Includes: |
array<numeric strings> | Each string is a list ID for exclusions. Create custom lists in Ads Manager or Marketing API, Publisher Block List. Example: |
For example, to use brand_safety_content_filter_levels
:
curl \ -F 'name=My AdSet' \ -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"]}, "brand_safety_content_filter_levels":["FACEBOOK_STRICT","AN_STANDARD"]}' \ -F 'status=ACTIVE' \ -F 'access_token=ACCESS_TOKEN' \ https://graph.facebook.com/VERSION/AD_ACCOUNT_ID/adsets
For Audience Network and In-Stream video you can also exclude publishers by category:
Name | Description |
---|---|
array<string> | Includes:
Example: |
Name: Options | Description |
---|---|
| Optional. |
| Optional. |
| Optional. Notes:
|
| Optional. |
| Optional. |
| Optional. Notes:
|
OR
.publisher_platforms=['facebook','instagram']
means deliver ads on Facebook and Instagram. AND
.publisher_platforms=['facebook']&device_platforms=['mobile']
means deliver these ads to Facebook Mobile only. publisher_platforms=['instagram']& device_platforms=['desktop']
, you will see an error.publisher_platforms: audience_network
cannot be selected by itself. audience_network
placement with the VIDEO_VIEWS
objective must be used with the THRUPLAYS
optimization goal.story
for facebook_positions
by itself. If you select story
for facebook_positions
, you must also select Facebook feed
or Instagram story
.story
for messenger_positions
by itself. If you select story
for messenger_positions
, you must also select either Facebook feed
or Instagram story
.stream
placement and are checked for web eligibility to be delivered to both desktop and mobile web feeds. The compatible objectives are BRAND_AWARENESS
, REACH
, LINK_CLICKS
, POST_ENGAGEMENT
, VIDEO_VIEWS
, and CONVERSIONS
.To use Facebook Stories as your placement:
curl \ -F 'name=My Ad Set' -F 'optimization_goal=CONVERSIONS' -F 'billing_event=IMPRESSIONS' -F 'bid_amount=2' -F 'daily_budget=1000' -F 'campaign_id=<AD_CAMPAIGN_ID>' -F 'targeting={"geo_locations":{"countries":["US"]}, "publisher_platforms":["messenger", "facebook"], "facebook_positions":["story"], "messenger_positions":["story"]}' -F 'status=ACTIVE' -F 'access_token=<ACCESS_TOKEN>' https://graph.facebook.com/API_VERSION/act_AD_ACCOUNT_ID/adsets
To create an ad set with only instream_video
placement that targets a supported country listed above:
curl \ -F 'name=My AdSet' \ -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"]},"publisher_platforms":["facebook"], "facebook_positions":["instream_video"]}' \ -F 'status=ACTIVE' \ -F 'access_token=ACCESS_TOKEN' \ https://graph.facebook.com/API_VERSION/act_AD_ACCOUNT_ID/adsets
To target the Audience Network Rewarded Video placement:
curl \ -F 'name=My Ad Set' \ -F 'optimization_goal=OFFSITE_CONVERSIONS' \ -F 'billing_event=IMPRESSIONS' \ -F 'is_autobid=true' \ -F 'daily_budget=40000' \ -F 'campaign_id=<AD_CAMPAIGN_ID>' \ -F 'targeting={"app_install_state": "not_installed","geo_locations":{"countries":["US"]},"facebook_positions":["feed"],"device_platforms": ["mobile"],"audience_network_positions": ["classic","rewarded_video"],"user_device": ["Android_Smartphone","Android_Tablet"],"user_os": ["Android_ver_4.4_and_above"]}' \ -F 'promoted_object={"application_id": "<APPLICATION_ID>","custom_event_type": "PURCHASE","object_store_url": "<OBJECT_STORE_URL>"}' \ -F 'status=ACTIVE' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/<APIVERSION>/<AD_ACCOUNT_ID>/adsets
This returns:
{ "targeting": { "audience_network_positions": [ "classic", "rewarded_video" ], "effective_audience_network_positions": [ "classic", "rewarded_video" ] }, "id": "<AD_SET_ID>" }
To use Facebook Reels as your placement:
curl \ -F 'name=My AdSet' \ -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"]},"publisher_platforms":["facebook"], "facebook_positions":["facebook_reels"]}' \ -F 'status=ACTIVE' \ -F 'access_token=ACCESS_TOKEN' \ https://graph.facebook.com/API_VERSION/act_AD_ACCOUNT_ID/adsets
To create an ad set with the explore_home
placement that targets a supported country (e.g., "US"):
curl -X POST \
-F 'name="My AdSet"' \
-F 'optimization_goal="LINK_CLICKS"' \
-F 'billing_event="IMPRESSIONS"' \
-F 'bid_amount=2' \
-F 'daily_budget=1000' \
-F 'campaign_id="<AD_CAMPAIGN_ID>"' \
-F 'targeting={
"geo_locations": {
"countries": [
"US"
]
},
"publisher_platforms": [
"instagram"
],
"instagram_positions": [
"stream",
"explore",
"explore_home"
],
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/adsets
To create an ad set with the ig_search
placement that targets a supported country (e.g., "US"):
curl -X POST \
-F 'name="My AdSet"' \
-F 'optimization_goal="LINK_CLICKS"' \
-F 'billing_event="IMPRESSIONS"' \
-F 'bid_amount=2' \
-F 'daily_budget=1000' \
-F 'campaign_id="<AD_CAMPAIGN_ID>"' \
-F 'targeting={
"geo_locations": {
"countries": [
"US"
]
},
"publisher_platforms": [
"instagram"
],
"instagram_positions": [
"stream",
"ig_search"
],
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/adsets
You create ad sets with placements in the targeting spec, however you do not always know if Facebook delivered your ad to the placements specified. This is because your selected placement may not apply to your chosen advertising objective. With the effective placements API for targeting, you can determine which placements your ad will deliver to, given your targeting options, and receive validation messages to understand why some placements are filtered out. If you do not provide targeting, you can still determine the effective placement based on ad set and ad campaign settings.
To read an effective placement based on your targeting, put effective_
in front of the placement field name. For example:
curl -G \ -d "fields=targeting{effective_publisher_platforms,effective_facebook_positions,effective_device_platforms,effective_audience_network_positions,effective_instagram_positions}" \ -d "access_token=<access_token>" \ https://graph.facebook.com/<VERSION>/<AD_SET_ID>
To see why some placements got filtered out use the recommendation
field:
curl -G \ -d "fields=recommendations" \ -d "access_token=<access_token>" \ https://graph.facebook.com/<VERSION>/23842573364570019
With the effective placements, you can determine which placements your ad will deliver to based on your ad set's billing_event
, optimization_goal
and promoted_object
as well as your ad campaign's buying_type
and objective
. All parameters for /ad_campaign_placement
include:
account_id
and access tokenbilling_event
, such as IMPRESSIONS
AUCTION
POST_ENGAGEMENT
POST_ENGAGEMENT
PIXEL_ID
All parameters except for promoted_object
and optimization_goal
are required. If you do provide targeting, you can use Marketing API to determine the effective placement based on the ones permitted for your settings, see Effective Placement with Targeting. For example:
curl -G \ -d 'account_id=<ACCOUNT_ID>' \ -d 'billing_event=IMPRESSIONS' \ -d 'buying_type=AUCTION' \ -d 'objective=PAGE_LIKES' \ -d 'optimization_goal=IMPRESSIONS' \ https://graph.facebook.com/<VERSION>/ad_campaign_placement?access_token=<TOKEN>
The call returns:
{ "effective_device_platforms": [ "mobile", "desktop" ], "effective_facebook_positions": [ "feed", "right_hand_column" ], "effective_publisher_platforms": [ "facebook" ], "recommendations": [ { "title": "Placement Not Supported By Objective", "message": "Ads with PAGE_LIKES objective do not support facebook.instream_video, facebook.suggested_video, facebook.marketplace, audience_network.classic, audience_network.instream_video, audience_network.rewarded_video, instagram.stream, instagram.story, messenger.messenger_home.", "code": 1815609, "importance": "LOW", "confidence": "HIGH", "blame_field": "targeting" }, { "title": "Device Platform Not Supported By Objective", "message": "Ads with PAGE_LIKES objective do not support connected_tv.", "code": 1815610, "importance": "LOW", "confidence": "HIGH", "blame_field": "targeting" } ], } }
You can use the code
field from this result in a call to /ad-recommendation
to see a detailed reason. For example, you can get this information:
[{“code”: 1815610, “summary”: “Device Platform Not Supported By Objective”},]
For more information, see Ad Recommendation, Reference and Effective Placement with Targeting.