Marketing API - Changelog

As of version 2.5, future Marketing API changelogs will be published under the Graph API Changelog.

October 7th, 2015 - Marketing API v2.5

Version v2.4 will be available until April, 2016. Before that, you should migrate your API calls to v2.5.

Going forward, Marketing API changelogs will be published under the Graph API Changelog.

July 8th, 2015 - Marketing API v2.4

Version v2.3 will be available until Oct 7th, 2015. Before that date, you should migrate your API calls to v2.4.

New Features

Labels API

A new API that lets developers tag campaigns/adsets/ads/creatives with arbitrary strings (“labels”) and organize/group their ad objects. The Labels API also allows querying adobjects by labels, including AND/OR queries, and query aggregated Insights by label. Now it is possible to answer questions like “how many clicks did all adsets with the 'US-country' label get?”


Added a new field 'app_install_state' in the ad set's targeting which takes a enum value of {installed, not_installed}. This field is intended to make inclusion/exclusion targeting for apps easier. The field can be used for any objective, but will only take effect if a promoted object is present.


  • Optimization simplification: We're simplifying how the optimization is specified in the data model by decoupling the bid fields into 3 separate fields. With this simplification, we should be able to significantly reduce the confusion around optimization specification in both the API and our UIs. See optimization simplification for more details.
  • The new fields on the ad set are:
  • optimization_goal: What the advertiser is optimizing for (video_views, link_clicks, etc...)
  • billing_event (required): What the advertiser is paying by (pay per impression, pay per link click, pay per video view etc...)
  • bid_amount: The value the advertiser is bidding per optimization goal
  • rtb_flag which should be used in favor of bid_type=CPM_RTB.
  • The new fields on the ad are:
  • bid_amount: The value the advertiser is bidding per optimization goal
  • The removed fields on the ad set are:
  • bid_info: will be removed on all write paths but can still be read. Use ad set's bid_amount field instead.
  • bid_type
  • The removed fields on the ad are:
  • bid_info: will be removed on all write paths but can still be read. Use ad's bid_amount field instead.
  • conversion_specs: will be removed on all write paths but can still be read. Use ad set's optimization_goal field instead.
  • is_autobid
  • Updating CPC to focus on link clicks - in order to make our advertisers' campaigns on Facebook more effective, we are updating the definition of cost per click (CPC). Today, when an advertiser runs a CPC ad, Facebook counts any action taken within the ad unit as a click: a like, a comment, a share, “continue reading”, a video view, a link click, etc. Starting v2.4, we are updating our definition of CPC ads to separate link clicks from engagement clicks (including likes and comments), and CPC will only include link clicks. To continue to optimize for likes, comments, shares, etc. as well as link clicks, advertisers can use billing_event=POST_ENGAGEMENT and optimization_goal=POST_ENGAGEMENT (or in v2.3 terms, CPA for Page Post Engagement).
  • Legacy ad sets bidding the v2.3- definition of CPC will be represented in v2.4 as having billing_event=POST_ENGAGEMENT and optimization_goal=POST_ENGAGEMENT
  • Old statistics APIs are being deprecated in favor of Insights Edge: With the launch of the Insights edge, we now have a single, consistent Insights API that advertisers can use to get all their metrics in one place. The Insights edge supports both sync and async queries, plus has new features like hourly breakdowns. With v2.4, stats, conversion stats and report stats APIs are deprecated.
  • Ads insights placement breakdown result will merge desktop_non_feed and desktop_right_hand into desktop_right_hand
  • Targeting
  • Split page_types into an array of single items, e.g. Instead of page_types:['desktop-and-mobile-and-external'] you would specify: page_types=['desktopfeed', 'rightcolumn', 'mobilefeed', 'mobileexternal']. The previously available groupings of page_types and validations remain the same.
  • Note that the previous definition of ['mobile'] or ['mobilefeed-and-external'] must now be replaced with ['mobilefeed', 'mobileexternal']
  • When not specifying a placement in targeting of an ad set, by default Facebook will include Audience Network page_types, and may include other page_types without notice in the future.
  • Deprecate conjunctive_user_adclusters and excluded_user_adclusters in favor of flexible targeting
  • Deprecate ad tags API in favor of new ad labels
  • Additional invalidations based on bid-budget ratios, please see ad set documentation for more details.
  • The 'Authorized Advertiser Emails and System User IDs' to set permissions on an app via App settings > Advanced. You must instead use an Ad account ID in the 'Authorized Ad Account IDs' field, or delegate access via Business Manager. act_{AD_ACCOUNT_ID}/connectionobjects will no longer return connections based on advertiser email.
  • Deprecate the conversion pixel status field. Developers should instead use last_firing_time
  • subtype will become a required parameter in custom audience and lookalike creation
  • Ad account TOS list returns enum string instead of FBID. Instead of { "tos_accepted": { "206760949512025": 1, "215449065224656": 1 }, return "tos_accepted": {"web_custom_audience_tos": 1, "custom_audience_tos": 1 }
  • Remove daily_spend_limit from ad account
  • Campaign spend_cap type change from uint32 to numeric string
  • Ad set DAILY_BUDGET, BUDGET_REMAINING, LIFETIME_BUDGET type change from uint32 to numeric string

For the full list of Graph API changes, refer to the Graph API changelog.

March 25th, 2015 - Marketing API v2.3

Version v2.2 will be available till July 8, 2015. Before that date, you should migrate your API calls to v2.3.

New Features

New Insights Edge

A new /insights edge consolidates functionality among /stats, /conversions, and /reportstats edges. It provides a single, consistent interface for ad insights. This edge is provided with every ad object node, including Business Manager. It provides functionality such as grouping results by any level, sorting, filtering on any field, and real time updates for asynchronous jobs.

Chunked Ad Video Upload

The new preferred way to upload ad videos is to do it chunk by chunk. When you upload an ad video, especially large ones, this method greatly increases the stability of video uploads. The previous one-step video uploading API still works, but we suggest you to switch to the new method for all videos.


  • Ad Sequencing in R&F Campaigns
  • Added interval_frequency_cap_reset_period to R&F which allows you to set a custom period of time that a frequency is applied to. Previously the cap was applied to the entire duration of the campaign.
  • Lowered the minimum audience from 1.5M people to 300K people and minimum reach to 200K people. This means that if you select a target audience with 300K people, the minimum number of people we require you to reach within that audience is 200K.


  • API support for video remarketing
  • Video available for page like, website conversions, local awareness, and mobile app install objectives
  • Added CPV bidding

Leads Ads

Introduced new lead ad unit designed to capture leads within Facebook's native platforms.

Carousel Ads

Carousel end card now optional


  • Campaign spend cap
  • Added auto bidding (is_autobid) to ad set object
  • For Global Pages, targeting a child Page will truly target the child Page and no longer target the entire hierarchy of pages.
  • Added CALL_NOW and MESSAGE_PAGE call to action for local awareness ads


The following summarizes all changes. For more information on upgrading, including code samples, see Facebook Marketing API Upgrade Guide.

Ad Account

  • The amount_spent, balance, daily_spend_limit, and spend_cap fields for an ad account are changed from integers to numeric strings.
  • The business field of /act_{AD_ACCOUNT_ID} and /{USER_ID}/adaccounts is now a JSON object.
  • 10 ad account capabilities are deprecated. You would not see those capabilities of your ad account. They are:

Pixels and Audiences

  • The field name is required while creating a Custom Audience pixel for an ad account using the /act_{AD_ACCOUNT_ID}/adspixels endpoint.
  • The field pixel_id is required while creating website custom audiences using the /act_{AD_ACCOUNT_ID}/customaudiences endpoint.

Ad Campaign, Ad Set, and Ad

  • An HTTP DELETE request to ad campaign, ad set, or ad will change its status to DELETED.
  • You need to specify the timezone of the start_time and end_time fields when updating an ad set.
  • When specifying a promoted_object in an ad set for an offer ad, you will provide the page_id instead of the offer_id.
  • The bid_info field of ad set or ad will not be available if is_autobid of the ad set is true.
  • The creative_ids field of an ad is no longer available.
  • The objective field of an ad is no longer available.
  • The multi_share_optimized field defaults to true now. You use this field when you create a Multi Product Ad with /{PAGE_ID}/feed or object_story_spec in /act_{AD_ACCOUNT_ID}/adcreatives.

Business Manager

  • The endpoint /{APP_SCOPED_SYSTEM_USER_ID}/ads_access_token is replaced by /{APP_SCOPED_SYSTEM_USER_ID}/access_tokens, for Business Manager System User access token management.

Reach Estimate and Targeting

  • Reach Estimate APIs, like all the other Marketing APIs, should be called with a user access token, instead of a Page access token.
  • The field params is removed from the response of targeting description obtained with /{AD_GROUP_ID}/targetingsentencelines
  • Both the placement options mobile and mobilefeed-and-external places ads on News Feed on mobile as well as on Audience Network. The new option mobilefeed is for News Feed on mobile only. You specify the placement option with page_types field of targeting specs.

Affected Endpoints

  • /{APP_SCOPED_SYSTEM_USER_ID}/ads_access_token
  • /act_{AD_ACCOUNT_ID}
  • /act_{AD_ACCOUNT_ID}/adcreatives
  • /act_{AD_ACCOUNT_ID}/adgroups
  • /act_{AD_ACCOUNT_ID}/adcampaigns
  • /act_{AD_ACCOUNT_ID}/adspixels
  • /act_{AD_ACCOUNT_ID}/customaudiences
  • /act_{AD_ACCOUNT_ID}/reachestimate
  • /act_{AD_ACCOUNT_ID}/targetingsentencelines
  • /{USER_ID}/adaccounts
  • /{CAMPAIGN_GROUP_ID}/adgroups
  • /{AD_SET_ID}
  • /{AD_SET_ID}/adgroups
  • /{AD_ID}
  • /{AD_ID}/targetingsentencelines
  • /{PAGE_ID}/feed

October 30th, 2014 - Marketing API v2.2

This is Facebook's first new API update after versioning was announced. API versions are supported for 90 days after the next version is released. This means that version 2.1 would be available until 90 days from v2.2, January 28, 2015. However, we have extended the adoption timeline for v2.2 this time to March 11, 2015. For more information, please see our blog post.


The below is a summarized list of all changes. For more info on upgrading, including code samples, please see our expanded upgrade guide.

Bid and Targeting

  • targeting and bid_type will be required at ad set level, and will no longer be available at ad level.
  • bid_info will be required at ad set level, while optional at ad level.
  • Action Spec targeting, which is a beta feature, will no longer be supported.

Affected Endpoints:

  • /act_{AD_ACCOUNT_ID}/adgroups
  • /act_{AD_ACCOUNT_ID}/adcampaigns
  • /{CAMPAIGN_GROUP_ID}/adcampaigns
  • /{CAMPAIGN_GROUP_ID}/adgroups
  • /{AD_SET_ID}/adgroups
  • /{AD_SET_ID}
  • /{AD_ID}

Required promoted_object field on Ad Set creation

A new field promoted_object will be required for creating an ad set when the campaign objective is website conversions, page likes, offer claims, mobile app install/engagement or canvas app install/engagement.

  • It will need to be set at creation and cannot be changed, if it needs to be changed a new ad set must be created.
  • Existing ad sets without a promoted_object will not be allowed to set a promoted_object. You must create a new ad set if you want to specify a promoted_object. Those existing ad sets without that setting will still run, and still can be updated/deleted as usual.
  • When promoted_object is specified, conversion_specs will be automatically inferred from the objective and promoted_object combo and cannot be changed/overwritten.
  • Additional validation will occur to ensure the ad is promoting the same object as specified in promoted_object.

Affected Endpoints:

  • /{AD_SET_ID}

Reach and Frequency

  • The target_specs endpoint will be replaced with target_spec, only allowing for one spec per prediction.
  • The new target_spec field returns an object where target_specs used to return an array.
  • A new field, story_event_type, will be added. This field will be used to specify when an ad set may or may not have video ads and is required when targeting all mobile devices.

Custom Audience Targeting

  • Advertisers will need to specify one or many App IDs when adding, removing, or opt-ing out users from Custom Audiences based on the Facebook user ID or app-scoped user ID.
  • By requiring an App ID, Facebook is ensuring that the Custom Audiences created only include IDs associated with people who have actually logged in or engaged with an advertiser’s app.
  • The app_ids field is required when "schema"="UID".
use FacebookAds\Object\CustomAudience;
use FacebookAds\Object\Values\CustomAudienceTypes;

// Add Facebook IDs of users of certain applications
$audience = new CustomAudience(<CUSTOM_AUDIENCE_ID>);
  array(<USER_ID_1>, <USER_ID_2>),
from facebookads.adobjects.customaudience import CustomAudience

audience = CustomAudience('<CUSTOM_AUDIENCE_ID>')
users = ['<USER_ID_1>', '<USER_ID_2>']
apps = ['<APP_ID>']
audience.add_users(CustomAudience.Schema.uid, users, '<APP_ID>'s=apps)
User user = new CustomAudience(<CUSTOM_AUDIENCE_ID>, context).createUser()
  .setPayload("{\"schema\":\"UID\",\"data\":[\"" + <USER_ID_1> + "\",\"" + <USER_ID_2> + "\"],\"app_ids\":[\"" + <APPLICATION_ID> + "\"]}")
curl \
  -F 'payload={ 
    "schema": "UID", 
    "data": ["<USER_ID_1>","<USER_ID_2>"], 
    "app_ids": ["<APPLICATION_ID>"] 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \<CUSTOM_AUDIENCE_ID>/users

New Graph API framework conversion

Starting with version 2.2 the following changes will be in affect for the endpoints below.

  • OAuthInsufficientScopeException will now be replaced by a GraphMethodException.
  • count, offset, and limit will no longer be returned and you must instead use a cursor-based approach to paging.
  • total_count is only returned when the flag summary=true is set.

Affected Endpoints:

  • /act_{AD_ACCOUNT_ID}/asyncadgrouprequestsets
  • /act_{AD_ACCOUNT_ID}/adreportschedules
  • /{SCHEDULE_REPORT_ID}/adreportruns
  • /act_{AD_ACCOUNT_ID}/stats
  • /act_{AD_ACCOUNT_ID}/adcampaignstats
  • /act_{AD_ACCOUNT_ID}/adgroupstats
  • /act_{AD_ACCOUNT_ID}/conversions
  • /act_{AD_ACCOUNT_ID}/adcampaignconversions
  • /act_{AD_ACCOUNT_ID}/adgroupconversions
  • /act_{AD_ACCOUNT_ID}/connectionobjects
  • /act_{AD_ACCOUNT_ID}/partnercategories
  • /act_{AD_ACCOUNT_ID}/reachfrequencypredictions
  • /act_{AD_ACCOUNT_ID}/asyncadgrouprequestsets
  • /act_{AD_ACCOUNT_ID}/broadtargetingcategories
  • /act_{AD_ACCOUNT_ID}/targetingsentencelines
  • /act_{AD_ACCOUNT_ID}/ratecard
  • /act_{AD_ACCOUNT_ID}/reachestimate
  • /act_{AD_ACCOUNT_ID}/users
  • /{AD_ACCOUNT_GROUP}/users
  • /{AD_ACCOUNT_GROUP}/adaccounts
  • /{CAMPAIGN_ID}/asyncadgrouprequests
  • /{ADGROUP_ID}/reachesttimate
  • /{ADGROUP_ID}/keywordstats
  • /{ADGROUP_ID}/targetingsentencelines
  • /search?type=adgeolocation (location_types: city, region)
  • /search?type=adlocale
  • /search?type=adworkemployer
  • /search?type=adworkposition
  • /search?type=adeducationschool
  • /search?type=adzipcode
  • /search?type=adcountry
  • /search?type=adcity
  • /{CUSTOM_AUDIENCE_ID}/adaccounts
  • /{ASYNC_REQUEST_SET_ID}/requests/
  • /{USER_ID}adaccounts which has additional changes:
  • business returns an ID rather than an object.
  • users returns a object with fields id rather than uid, permissions, and role.
  • A new field, created_time, which is the time that the account was created.