video_id must be associated with the ad account.VIDEO_VIEWS objective and optimize the bid for reach, follow these steps:pages_read_engagement and ads_management permissionsact_{ad-account-id}/advideos endpointcurl \
-F 'name=Sample Creative' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"video_data": {"image_url":"<THUMBNAIL_URL>","video_id":"<VIDEO_ID>"}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
VIDEO_VIEWS:curl -X POST \
-F 'name="Video Views campaign"' \
-F 'objective="OUTCOME_ENGAGEMENT"' \
-F 'status="PAUSED"' \
-F 'special_ad_categories=[]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/campaigns
optimization_goal=THRUPLAY. You can set bidding_event to IMPRESSIONS or THRUPLAY, to pay per impression or per video view. See CPV bidding.curl \
-F 'name=A CPV Ad Set' \
-F 'campaign_id=<CAMPAIGN_ID>' \
-F 'daily_budget=500' \
-F 'start_time=2024-05-06T04:45:29+0000' \
-F 'end_time=2024-06-06T04:45:29+0000' \
-F 'billing_event=THRUPLAY' \
-F 'optimization_goal=THRUPLAY' \
-F 'bid_amount=100' \
-F 'targeting={
"device_platforms": ["mobile"],
"geo_locations": {"countries":["US"]},
"publisher_platforms": ["facebook"]
}' \
-F 'status=PAUSED' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adsets
optimization_goal=THRUPLAY compared to CPVs from Reach and Frequency buying optimized for video views.The end date must be in the future. See Reference: Ad Set.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/v25.0/act_<AD_ACCOUNT_ID>/ads
VIDEO_VIEWS, by default the ad gets the right tracking specs which define actions tracked for an ad. For example, video views:{'action.type':'video_view','post':'POST_ID','post.wall':'PAGE_ID'}
-F "rf_prediction_id=<RESERVATION_ID>" \
subtype=ENGAGEMENT. Then write rules for the audience you want to create. Each rule has an object_id, such as video ID, and event_name. The event_name is one of:video_watched: the number of times your video was watched for an aggregate of at least 3 seconds, or for nearly its total length, whichever happened first.video_completed: the number of times your video was watched at 95% of its length, including watches that skipped to this point.video_view_10s: the number of times your video was watched for an aggregate of at least 10 seconds, or for nearly its total length, whichever happened first.video_view_15s: the number of times your video was watched for an aggregate of at least 15 seconds, or for nearly its total length, whichever happened first.video_view_25_percent: the number of times your video was watched at 25% of its length, including watches that skipped to this point.video_view_50_percent: the number of times your video was watched at 50% of its length, including watches that skipped to this point.video_view_75_percent: the number of times your video was watched at 75% of its length, including watches that skipped to this point.prefill=true.curl \
-F 'name=Video Ads Engagement Audience' \
-F 'subtype=ENGAGEMENT' \
-F 'description=Users who watched my video' \
-F 'prefill=1' \
-F 'rule=[
{"object_id":"%video_id_1","event_name":"video_watched"},
{"object_id":"%video_id_2","event_name":"video_completed"}
]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/customaudiences
PAGE_LIKESLEAD_GENERATIONLOCAL_AWARENESSLINK_CLICKSCONVERSIONSAPP_INSTALLSVIDEO_VIEWSBRAND_AWARENESSGET_DIRECTIONS call to action:curl \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"video_data": {
"call_to_action": {
"type": "GET_DIRECTIONS",
"value": {
"link": "fbgeo:\/\/37.48327, -122.15033, \"1601 Willow Rd Menlo Park CA\""
}
},
"image_url": "<THUMBNAIL_URL>",
"link_description": "Come check out our new store in Menlo Park!",
"video_id": "<VIDEO_ID>"
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
action_video_type in action_breakdowns. Expected values for action_video_type are total, click_to_play, and auto_play.action_video_type option. To identify clients with the breakdown, check CAN_USE_VIDEO_METRICS_BREAKDOWN for the ad account.curl -G \
-d 'action_breakdowns=action_video_type' \
-d 'date_preset=last_30_days' \
-d 'fields=actions,video_avg_pct_watched_actions,video_complete_watched_actions' \
-d 'access_token= <ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/insights
action_type as video_view and contain a key action_video_type:{
"data": [
{
"actions": [
...
{
"action_type": "video_play",
"value": 9898
},
{
"action_type": "video_view",
"action_video_type": "total",
"value": 921129
},
{
"action_type": "video_view",
"action_video_type": "auto_play",
"value": 915971
},
{
"action_type": "video_view",
"action_video_type": "click_to_play",
"value": 5158
}
],
"video_avg_pct_watched_actions": [
{
"action_type": "video_view",
"action_video_type": "total",
"value": 60.59
},
{
"action_type": "video_view",
"action_video_type": "auto_play",
"value": 60.47
},
{
"action_type": "video_view",
"action_video_type": "click_to_play",
"value": 80.63
}
],
"video_complete_watched_actions": [
{
"action_type": "video_view",
"action_video_type": "total",
"value": 156372
},
{
"action_type": "video_view",
"action_video_type": "auto_play",
"value": 154015
},
{
"action_type": "video_view",
"action_video_type": "click_to_play",
"value": 2357
}
],
"date_start": "2014-12-26",
"date_stop": "2015-03-25"
}
],
"paging": {
"cursors": {
"before": "MA==",
"after": "MA=="
}
}
}
object_story_spec, which creates an unpublished page post from adcreatives. See ad creatives. For example:curl \
-F 'name=Sample Creative' \
-F 'object_story_spec={
"link_data": {
"child_attachments": [
{
"description": "$8.99",
"image_hash": "<IMAGE_HASH>",
"link": "https:\/\/www.link.com\/product1",
"name": "Product 1",
"video_id": "<VIDEO_ID>"
},
{
"description": "$9.99",
"image_hash": "<IMAGE_HASH>",
"link": "https:\/\/www.link.com\/product2",
"name": "Product 2",
"video_id": "<VIDEO_ID>"
},
{
"description": "$10.99",
"image_hash": "<IMAGE_HASH>",
"link": "https:\/\/www.link.com\/product3",
"name": "Product 3"
}
],
"link": "<URL>"
},
"page_id": "<PAGE_ID>"
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
{"id":"<CREATIVE_ID>"}
child_attachments is an array of link objects. On each link object, picture, name and description are optional. You can post these as by the Page only with a Page access token.curl -X GET \
-d 'message="Browse our latest products"' \
-d 'published=0' \
-d 'child_attachments=[
{
"link": "<APP_STORE_URL>",
"name": "Product 1",
"description": "$4.99",
"image_hash": "<IMAGE_HASH>"
},
{
"link": "<APP_STORE_URL>",
"name": "Product 2",
"description": "$4.99",
"image_hash": "<IMAGE_HASH>"
},
{
"link": "<APP_STORE_URL>",
"name": "Product 3",
"description": "$4.99",
"image_hash": "<IMAGE_HASH>"
},
{
"link": "<APP_STORE_URL>",
"name": "Product 4",
"description": "$4.99",
"image_hash": "<IMAGE_HASH>"
}
]' \
-d 'caption="WWW.EXAMPLE.COM"' \
-d 'link="http://www.example.com/products"' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/posts
id for the object_story_id in your ad creative.curl -X POST \
-F 'object_story_id="<PAGE_ID>_<POST_ID>"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
"child_attachments": [
{
"link": "https://www.facebookmarketingdevelopers.com/",
"name": "Facebook Marketing Developers",
"description": "Facebook Marketing Developers",
"call_to_action": {
"type": "APPLY_NOW",
"value": {
"link_title": "Facebook Marketing Developers"
}
},
"video_id": "123",
"caption": "mycustomlinkcaption.com"
},
]
child_attachment. You do not have to specify the link again in the call_to_action:{'value':{'link':... }}}curl -X POST \
-F 'name="Carousel app ad"' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"link_data": {
"message": "My message",
"link": "http://www.example.com/appstoreurl",
"caption": "WWW.ITUNES.COM",
"name": "The link name",
"description": "The link description",
"child_attachments": [
{
"link": "http://www.example.com/appstoreurl",
"image_hash": "<IMAGE_HASH>",
"call_to_action": {
"type": "USE_MOBILE_APP",
"value": {
"app_link": "<DEEP_LINK>"
}
}
},
{
"link": "http://www.example.com/appstoreurl",
"image_hash": "<IMAGE_HASH>",
"call_to_action": {
"type": "USE_MOBILE_APP",
"value": {
"app_link": "<DEEP_LINK>"
}
}
},
{
"link": "http://www.example.com/appstoreurl",
"image_hash": "<IMAGE_HASH>",
"call_to_action": {
"type": "USE_MOBILE_APP",
"value": {
"app_link": "<DEEP_LINK>"
}
}
},
{
"link": "http://www.example.com/appstoreurl",
"image_hash": "<IMAGE_HASH>",
"call_to_action": {
"type": "USE_MOBILE_APP",
"value": {
"app_link": "<DEEP_LINK>"
}
}
}
],
"multi_share_optimized": true
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
curl \
-F 'message=My description' \
-F 'link=<APP_STORE_URL>' \
-F 'caption=WWW.ITUNES.COM' \
-F 'child_attachments=[
{
"link": "<APP_STORE_URL>",
"image_hash": "<IMAGE_HASH_I>",
"call_to_action": {
"type": "USE_MOBILE_APP",
"value": {"app_link":"<DEEP_LINK_I>","link_title":"<LINK_TITLE_I>"}
}
},
{
"link": "<APP_STORE_URL>",
"image_hash": "<IMAGE_HASH_I>",
"call_to_action": {
"type": "USE_MOBILE_APP",
"value": {"app_link":"<DEEP_LINK_I>","link_title":"<LINK_TITLE_I>"}
}
},
{
"link": "<APP_STORE_URL>",
"image_hash": "<IMAGE_HASH_I>",
"call_to_action": {
"type": "USE_MOBILE_APP",
"value": {"app_link":"<DEEP_LINK_I>","link_title":"<LINK_TITLE_I>"}
}
},
{
"link": "<APP_STORE_URL>",
"image_hash": "<IMAGE_HASH_I>",
"call_to_action": {
"type": "USE_MOBILE_APP",
"value": {"app_link":"<DEEP_LINK_I>","link_title":"<LINK_TITLE_I>"}
}
}
]' \
-F 'multi_share_optimized=1' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/feed
id from the response to create the AdCreative:curl -X POST \
-F 'object_story_id="<PAGE_ID>_<POST_ID>"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives

| Name | Description |
|---|---|
child_attachmentstype: object | A 2-10 element array of link objects required for carousel ads. You should use at least 3 objects for optimal performance; 2 objects is for enabling lightweight integrations and using 2 objects can result in sub-optimal campaign results. |
child_attachments.linktype: string | Link URL or app store URL attached to the post. Required. |
child_attachments.picturetype: URL | Preview image associated with the link. 1:1 aspect ratio and a minimum of 458 x 458 px for best display. Either picture or image_hash must be specified. |
child_attachments.image_hashtype: string | Hash of preview image associated with the link from your image library; use 1:1 aspect ratio and a minimum of 458 x 458 px for best display. Either picture or image_hash must be specified. |
child_attachments.nametype: string | Title of link preview. If not specified, title of the linked page used. Typically truncated after 35 characters. You should set a unique name, since Facebook interfaces show actions reported by name. |
child_attachments.descriptiontype: string | Either a price, discount or website domain. If not specified, content from the linked page is extracted and used. Typically truncated after 30 characters. |
child_attachments.call_to_actiontype: object | Optional call to action. See Call To Action. You do not have to specify the link again in call_to_action:{'value':{'link':... }}} |
child_attachments.video_idtype: string | ID of the ad video. Can be used in any child-element. If specified, must also set image_hash or picture. |
messagetype: string | Main body of post, also called the status message. |
linktype: string | URL of a link to “See more”. Required. |
captiontype: string | URL to display in the “See more” link. Not applicable for carousel mobile app ads |
multi_share_optimizedtype: boolean | If set to true, automatically select and order images and links. Otherwise use original order of child elements. Defaults to true. |
multi_share_end_cardtype: boolean | If set to false, removes the end card which displays the page icon. Default is true. |
actions_breakdown=['action_carousel_card_id', 'action_carousel_card_name']. Each child_attachment has a different card ID. action_carousel_card_id and action_carousel_card_name is only for Carousel ads.website_ctr: available when specifying fields=['website_ctr']app_install, app_use, apps.uses, credit_spent, mobile_app_install, tab_view, link_click, mobile_app_install, app_custom_event.*, offsite_conversion.*: available when specifying fields=['actions']. Other actions are not available with a card breakdown.curl -G \
-d 'action_breakdowns=["action_type","action_carousel_card_id"]' \
-d 'level=ad' \
-d 'date_preset=last_30_days' \
-d 'time_increment=all_days' \
-d 'breakdowns=placement' \
--data-urlencode 'filtering=[
{
"field": "action_type",
"operator": "IN",
"value": ["link_click"]
}
]' \
-d 'fields=impressions,inline_link_clicks,actions,website_ctr' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/insights
{
...
"website_ctr": [
{
"action_carousel_card_id": "1",
"action_type": "link_click",
"value": 51.401869158878
},
{
"action_carousel_card_id": "2",
"action_type": "link_click",
"value": 50.980392156863
}
],
"placement": "mobile_feed",
"date_start": "2015-05-25",
"date_stop": "2015-05-28"
}
cost_per_action_type for a breakdown of costs by action type:curl -G \
-d 'action_breakdowns=["action_type","action_carousel_card_name"]' \
-d 'level=ad' \
-d 'breakdowns=placement' \
-d 'fields=impressions,campaign_name,cost_per_action_type' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/insights
{
"data": [
{
"impressions": "1862555",
"campaign_name": "My Campaign",
"cost_per_action_type": [
{
"action_carousel_card_name": "My Carousel Card 1",
"action_type": "app_custom_event.fb_mobile_activate_app",
"value": 0.093347346315861
},
{
"action_carousel_card_name": "My Carousel Card 2",
"action_type": "app_custom_event.fb_mobile_activate_app",
"value": 0.38324089579301
},
...
],
}
]
}
action_report_time=impression are inaccurate before June 20th, 2015.action_report_time=conversion are inaccurate before July 20th, 2015.right_hand_column as your placement, you can only use a single-video or carousel format in your ad group. We do not support the video format with a only a right_hand_column placement selected. See Advanced Targeting and Placement.right_hand_column as your only placement:curl \
-F 'name=RHS only Ad Set' \
-F 'campaign_id=<CAMPAIGN_ID>' \
-F 'daily_budget=500' \
-F 'start_time=2017-11-21T15:41:36+0000' \
-F 'end_time=2017-11-28T15:41:36+0000' \
-F 'billing_event=IMPRESSIONS' \
-F 'optimization_goal=LINK_CLICKS' \
-F 'bid_amount=100' \
-F 'targeting={
"device_platforms": ["mobile"],
"geo_locations": {"countries":["US"]},
"publisher_platforms": ["facebook"] ,
"facebook_positions": ["right_hand_column"] ,
}' \
-F 'status=PAUSED' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adsets
curl \
-F 'name=Sample Creative' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"video_data": {"image_url":"<THUMBNAIL_URL>","video_id":"<VIDEO_ID>"}
}' \
-F 'access_token=ACCESS_TOKEN' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
curl \
-F 'image_hash=<IMAGE_HASH>' \
-F 'object_story_spec={
"link_data": {
"call_to_action": {"type":"LEARN_MORE"},
"image_hash": "<IMAGE_HASH>",
"link": "CANVAS_LINK",
"name": "Creative message"
},
"page_id": "<PAGE_ID>"
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
curl \
-F 'name=My Ad' \
-F 'adset_id=<AD_SET_ID>' \
-F 'creative={"creative_id":"<CREATIVE_ID>"}' \
-F 'status=ACTIVE' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/ads