Create a Meta ad with a focus on available reels placements and learn best practices around our ads operations.
If you do not meet those prerequisites, please refer to our developer documentation.
Meta offers a testing environment, which doesn't actually deliver ads, but allows you to:
Read through our testing best practices.
An access token is an opaque string that identifies a user, app, or Page and can be used by the app to make graph API calls. You can see when it expires and which app generated it. Marketing API calls on Meta apps need to include an access token.
Get an access token with necessary permissions:
ads_management
: make changes in selected ad accounts
ads_read
: read out ads data
read_insights
: read out performance insights
Use system access tokens as they have longer expiration times.
To access Marketing API endpoints, you need to create a Business app. They are subject to an additional layer of Graph API authorization called access levels. During App Review, your app must also request specific permissions and features. You must complete Business Verification if your app will be used by app users who do not have a role on the app itself, or a role in a Business that has claimed the app.
If your app is managing other people’s ad accounts, you need:
ads_read
and/or
ads_management
Fetch your advertisers ad account(s) and allow them to select the one for ads creation.
Through our Business Management API, you can see all the ad accounts their business has access to. This returns all ad accounts owned by a business. Note that you will need the business_management
permission at app and user level. Refer to Business Asset Management APIs.
curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v21.0
/<BUSINESS_ID>/owned_ad_accounts"
A campaign is the highest level organizational structure within an ad account and should represent a single objective for an advertiser. These objects contain your advertising objective and one or more ad sets. This helps you optimize and measure results for each advertising objective. Learn more about creating, reading, updating and deleting a campaign here.
curl -X POST \
-F 'name="My campaign"' \
-F 'objective="OUTCOME_TRAFFIC"' \
-F 'status="PAUSED"' \
-F 'special_ad_categories=[]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/campaigns
To enable advertisers to reach specific groups, specific these parameters in your API requests:
Then potential customers who are most likely to be interested in your products or services will be reached.
curl -X POST \
-F 'access_token=YOUR_ACCESS_TOKEN' \
-F 'name=My Custom Audience' \
-F 'subtype=CUSTOM' \
-F 'description=People who live in New York, aged 25-40, interested in technology' \
-F 'customer_file_source=USER_PROVIDED_ONLY' \
-F 'targeting_spec={
"geo_locations": {
"countries": ["US"],
"regions": [{"key": "4081"}] # New York region key
},
"age_min": 25,
"age_max": 40,
"interests": [{"id": "6003139266461", "name": "Technology"}]
}' \
https://graph.facebook.com/v21.0
/act_YOUR_AD_ACCOUNT_ID/customaudiences
Ad sets can have one or more ads. Ads within an ad set should have the same targeting, budget, billing, optimization goal, and duration.
You can set the budget, schedule, targeting, bid strategy, and placement options. Ad sets allow for fine-tuning how and where ads are delivered to specific audience segments, optimizing performance, and achieving marketing goals.
Key parameters:
More comprehensive details here.
You can pick a manual placement that includes Instagram and Facebook reels ads, or default to automatic placements. If you do not specify anything for a particular placement field, it considers all possible default positions for that field.
curl -X POST \
-F 'access_token=YOUR_ACCESS_TOKEN' \
-F 'name=Reels Ad Set' \
-F 'campaign_id=YOUR_CAMPAIGN_ID' \
-F 'daily_budget=5000' \
-F 'billing_event=IMPRESSIONS' \
-F 'optimization_goal=REACH' \
-F 'start_time=2024-07-10T10:00:00-0700' \
-F 'end_time=2024-07-20T10:00:00-0700' \
-F 'targeting={"geo_locations":{"countries":["US"]},"age_min":18,"age_max":65}' \
-F 'promoted_object={"page_id":"YOUR_PAGE_ID"}' \
-F 'status=PAUSED' \
-F 'instagram_actor_id=YOUR_INSTAGRAM_ACTOR_ID' \
-F 'publisher_platforms=["instagram"]' \
-F 'instagram_positions=["reels"]' \
https://graph.facebook.com/v21.0
/act_YOUR_AD_ACCOUNT_ID/adsets
publisher_platforms | facebook_position or instagram position | Compatible Objectives | optimization_goal |
---|---|---|---|
instagram |
| OUTCOME_APP_PROMOTION |
|
instagram |
| OUTCOME_AWARENESS |
|
instagram |
| OUTCOME_LEADS |
|
instagram |
| OUTCOME_TRAFFIC |
|
instagram |
| OUTCOME_ENGAGEMENT |
|
instagram |
|
|
|
facebook | facebook_reels |
|
|
facebook | facebook_reels |
|
|
facebook | facebook_reels |
|
|
facebook | facebook_reels |
|
|
facebook | facebook_reels |
|
|
facebook | facebook_reels |
|
|
Compatible Objective +
optimization_goal Combination
| FB Reels Eligible? | IG Reels Eligible? |
---|---|---|
| ✅ | ❌ |
| ❌ | ✅ |
| ✅ | ❌ |
| ✅ | ❌ |
| ✅ | ❌ |
| ❌ | ✅ |
| ✅ | ❌ |
| ✅ | ❌ |
| ✅ | ❌ |
Ad creatives are the visual and textual components of ads, which support the following ad formats:
Automate design elements and optimize performance using our creative process.
Users can provide a new asset or repurpose an existing reel from their Instagram account as the ad creative.
You can create ads from existing, organic Instagram or Facebook reels that are eligible to be promoted, provided they are:
To repurpose an organic Instagram reel as the ad creative for a new ad campaign:
Obtain the Instagram Business account ID, which needs to be connected to a Facebook Page
GET/{ad_account_id}/connected_instagram_accounts
orGET/{business_id}/instagram_business_accounts
Find the Reel You Want to Promote
GET/{ig-business-account-user-id}/media
Provide Ad Creative
instagram_actor_id
in the creative spec, set instagram_user_id
as the Instagram user IDsource_instagram_media_id
as the media IDcall_to_action
for your promotionLeverage boost_eligibility_info
as a convenient way to determine whether media is eligible to be boosted as an ad and boost_ads_list
to trace related past boost Instagram ad information.
curl -i -X POST \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT>/adcreatives?object_id=<PAGE_ID>
&instagram_user_id=<IG_USER_ID>
&source_instagram_media_id=<IG_ORGANIC_MEDIA_ID>
&call_to_action="{'type':'LEARN_MORE','value':{'link': '<YOUR_LINK>'}}"
&access_token=<API_ACCESS_TOKEN>
You can automate the generation of diverse and engaging ad elements, such as: images, videos, and text. These AI-driven tools help optimize ad performance by tailoring content to audience preferences and enhancing creative variety. Ad creation will result in higher engagement and better campaigns.
Preview the ad in the Facebook and Instagram Reels formats tabulated below using:
PUBLISHING PLATFORM | Ad Format |
---|---|
| |
|
curl -X POST \
'https://graph.facebook.com/v21.0
/act_{ad_account_id}/adpreviews' \
-F 'access_token={your_access_token}' \
-F 'creative={
"object_story_spec": {
"instagram_actor_id": "{instagram_actor_id}",
"video_data": {
"video_id": "{video_id}",
"title": "Check out our new product!",
"description": "Exciting new features and benefits.",
"call_to_action": {
"type": "LEARN_MORE",
"value": {
"link": "https://www.example.com/product"
}
}
}
}
}' \
-F 'ad_format=INSTAGRAM_REELS'
To book an ad using the marketing API, create an ad group object and link your ad set object to the Ad Creative. Use /act_{ad_account_id}/ads
to submit your Ad object, and validate the response to confirm successful booking. This step finalizes your ad setup, making it ready for delivery based on the configurations provided.
curl -X POST \
-F 'name="My Ad"' \
-F 'adset_id="<AD_SET_ID>"' \
-F 'creative={
"creative_id": "<CREATIVE_ID>"
}' \
-F 'status="PAUSED"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/ads
Use the Insights API to fetch metrics from ad account to ads:
act_<AD_ACCOUNT_ID>/insights
<CAMPAIGN_ID>/insights
<ADSET_ID>/insights
<AD_ID>/insights
When running a campaign on Instagram and Facebook, add breakdowns=publisher_platform
to see the stats of Facebook and Instagram placements separately, as shown in the sample call below. When breaking down insights by Placement level, it will be possible to see how ads perform via Instagram and Facebook Reels placement.
curl -X GET \
'https://graph.facebook.com/v21.0
/{ad_account_id}/insights' \
-F 'access_token={your_access_token}' \
-F 'level=campaign' \
-F 'fields=campaign_name,impressions,clicks,spend' \
-F 'breakdowns=publisher_platform,platform_position' \
-F 'filtering=[{"field":"platform_position","operator":"IN","value":["instagram_reels"]}]' \
-F 'time_range={"since":"2024-06-01","until":"2024-06-30"}'
OUTCOME_APP_PROMOTION
OUTCOME_AWARENESS
OUTCOME_ENGAGEMENT
OUTCOME_LEADS
OUTCOME_SALES
OUTCOME_TRAFFIC
The Marketing API has its own rate limiting logic and is excluded from all the Graph API rate limitations. The feature that impacts the Marketing API rate limit quota is Ads Management Standard Access. By default, you get Standard Access when you add the Marketing API product to your App Dashboard, which provides you development access to the Marketing API. To increase the rate limiting quota, upgrade to Advanced Access.
Reels ads turn attention into action, supercharging results. When you build them the right way, they are even more effective.
1. Build in 9:16 video to make your video captivating: Reels is a full-screen, immersive video format. To help your creative feel at home here, consider leading with video and resizing it to 9:16.
2. Build in safe zones so that your messages are clear: Work within the safe zones so your text sticker overlays, calls to action or key messages aren’t obscured by the Reels user interface. Keep the bottom 35% of your 9:16 creative free of text, logos, and other key elements.
3. Build for sound on to make your video entertaining: Audio – whether that's music, voiceover or sound effects – is a key driver of engagement and entertainment on Reels.
Use Catalog Product Video for your Reels placements to enhance your catalog and ad experience. With Dynamic Media, you can deliver video assets from your catalog along with the existing product images in your Advantage+ catalog ads campaigns. Dynamic Media allows you to extend your reach to Instagram Reels and Facebook Reels. In addition, it consolidates multiple video campaigns into a single dynamic ad campaign. You can use Dynamic Media ads across different placements, but we focus on using Dynamic Media ads in Reels placements here.
Dynamic Media ads will show either images or videos of your catalog items based on what each person viewing your ad is likely to find engaging. Dynamic media uses automation and product ranking to deliver not only the most relevant products, but also the highest-performing assets to audiences across placements.
Catalog product video is supported across all catalog verticals, and Dynamic Media ads are open to all advertisers. Catalog product video is a good fit for advertisers who would like to enhance their Advantage+ catalog ads campaigns with more inspirational video creatives.
To create Dynamic Media ads that deliver on Reels, you will need a product catalog with existing products and at least one video for each product item in a downloadable video URL format. For more information, see Dynamic Media.
preferred_video_tags
on the adOUTCOME_SALES
, LINK_CLICKS
, APP_INSTALLS
, or CONVERSIONS
publisher_platforms
is set for ["instagram","facebook"]
, facebook_positions
and instagram_positions
are set for reelsproduct_set_id
in promoted_object
for your ad set to promote products from that product set