Changelog Archive

The latest version is:


These logs document versioned changes to the Graph API and Marketing API that are no longer available. To learn more about versions, please see our Platform Versioning documentation. Use the API Upgrade Tool to determine which version changes will affect your API calls. For more information on upgrading, please see our upgrade guide.

Breaking Changes are not included here since they are not tied to specific releases.

API VersionGraph API AvailabilityMarketing API Availability


April 18, 2017 - July 22, 2019

April 18, 2017 - November 6, 2017


October 5, 2016 - April 18, 2019

October 5, 2016 - July 26, 2017


July 13, 2016 - October 5, 2018

July 13, 2016 - April 25, 2017


April 12, 2016 - July 13, 2018

April 12, 2016 - October 5, 2016


October 7, 2015 - April 12, 2018

October 7, 2015 - July 13, 2016


July 8, 2015 - October 7, 2017

July 8, 2015 - April 11, 2016


March 25, 2015 - July 8, 2017

March 25, 2015 - October 8, 2015


October 30, 2014 - March 25, 2017

October 30, 2014 - July 8, 2015


August 7, 2014 - October 30, 2016

October 1, 2014 - March 11, 2015


October 1, 2014 - August 7, 2016

October 1, 2014 - March 11, 2015


April 21, 2010 - April 30, 2015

October 1, 2014 - March 11, 2015

Version 2.9

Graph API | Marketing API

Changelog entries are categorized in the following way:

  • New Features — New products or services, including new nodes, edges, and fields.
  • Changes — Changes to existing products or services (not including Deprecations).
  • Deprecations — Existing products or services that are being removed.
  • 90-Day Breaking Changes — Changes and deprecations that will take effect 90 days after the version release date.

New Features, Changes, and Deprecations only affect this version. 90-Day Breaking Changes affect all versions.

Breaking Changes are not included here since they are not tied to specific releases.

Graph API

Released April 18, 2017 | Available until July 18, 2019

New Features


  • Read After Write - Graph API POST requests now support returning specified values of an object during the same request as a write, saving a round trip for clients. If a fields parameter is specified (explanation of the syntax), the request will first do the write, then read the created or updated object, selecting fields using the fields parameter, as the response. Read-after-write is now enabled for all versions of the Graph API. Visit our docs page to learn more.

  • New short_names Field on the User Object - The following field has been added to the user endpoint:

    • short_name - first_name assumes the universally friendly way to refer to a person is by their first name. However, in many cultures (especially Chinese, Japanese, Korean, Thai, Indic, and a few others), it's inappropriate to address people by their first name. The new short_name method understands the culture-specific rules for how to address a person with a short name. So, for a viewer in the US, they'll continue to see friends in China, Japan, Korea, and India addressed by their first name, but their friends in East and South Asia will see friends with full names.


  • Business App Page Mapping - The user node has two new edges, ids_for_pages and ids_for_apps, for de-referencing a person's ID for an app or a page. The ids_for_pages edge returns other IDs that person has for pages owned by the same business. Similarly, the ids_for_apps edge returns other IDs that person has for apps owned by the same business. See Connecting with People Across Apps and Bots in Messenger.

  • Page POST Support to Add Pages to Crosspost Videos - Approve and accept a crossposting relationships request from another page by POST /{page_id}/crossposting_pages.

  • Webhooks IDs Are Serialized as Strings - Numeric IDs are converted to strings in this webhooks update.


Places Graph

  • Current Place - The following fields have been added:

    • GET /current_place/results - Helps determine what place a person is currently at by using location signals. User permission is required.
    • POST /current_place/feedback - Allows you to provide feedback about whether they were actually there. For more information, see Places Graph
  • GET /search?type=place - The following parameters have been added:

    • categories - Search by category.
    • matched_categories - Indicate which categories the resulting place matches. Must be used with categories.

Video APIs

  • Time Spent in Video Metrics for Page - The following metrics have been added. For more information, see Insights Metric /{object-id}/insights/{metric}.

    • page_video_view_time- The time spent on videos on the page.
    • post_video_view_time_by_country_id - The time spent on videos on the page by country.


  • Apps Can Receive Changed Values for User's Profile Updates with Webhooks Updates - When a user changes a field, your app can receive the new value as part of the update, saving the step of checking the value. Previously, whenever a user changed one of their fields, we would notify the app of the field that changed without sending the new value.

  • Documentation - Webhooks now has reference documentation for topics and fields you can subscribe to. This documentation is on Facebook Developers site under Webhooks Reference in the Graph API.

  • Sample Sender Tool - The new tool makes it easier for developers to test out the Webhooks update structure before subscribing to the topic. In the past, developers had to subscribe to a field and then try to trigger the update by making a change through Facebook. For example, an app might need to know when a user (users that installed the app and granted needed permissions) changes their profile picture. The app would subscribe to the profile picture field in the Webhooks framework. However, to test how this works, you had to change the profile picture on some user that had installed the app to see the structure of the update we send. The sample sender tool allows apps to test the update structure without having to make an unnecessary change. You can find the sample sender tool in the webhooks section of your app's dashboard.

  • Versioning - Webhooks versions are now the same as Graph API. Any existing Webhooks subscriptions will be running on the oldest supported version of the app. Previously, Webhooks subscriptions didn't support versioning. The only way to make changes was by making breaking changes. For more information on Webhooks versions, see Versioning.



  • The Batch API returns an error rather than a null response for aborted request items in the Batch API. For more information, see Graph API, Making Batch Requests.

  • GET /{url}/share - The share endpoint has been removed and replaced with:

    • engagement field with subfields:
      • comment_count
      • comment_plugin_count
      • reaction_count
      • share_count


  • /{page-id}/feed - Backdated posts are included in the {page_id}/feed request if the backdated_time of the post is within the since and until time range. The created_time is the actual creation time. (See changes to Posts below.)

  • page-restaurant-services - All fields now return false or true instead of 0 or 1.

  • GET /{post-id} - The following field has been added to this endpoint:
    • promotable_id - Previously, certain posts could not be promoted, only their contents. In such cases, the id field would return the contents ID, rather than the ID for the post. Posts now always return their own ID in the id field, and a new field, promotable_id, is added to the GET {post-id} endpoint to be used when promoting the post.


  • Backdating a post will no longer update the post's created_time value. Instead, it will duplicate the original, but with created_time and backdated_time set to the new value. The original post will keep its old created_time value and gain the new backdated_time and value. Finally, GET {post-id}/feed will no longer return the original post, but instead will return the newly created duplicate.

Video API

  • Expose dash preview URL for live video instead of RTMP URL.

  • GET /{page_id}/crosspost_pending_approval_pages - List all the Pages your Page has sent crossposting requests, but that have not accepted yet.

  • GET /{page_id}/crosspost_whitelisted_pages - List all the pages you have given crossposting permission.

  • POST /{video_id}/allow_crossposting_for_pages = [{"page_id": {page_id}, "allow": {true/false}] - Allow or disallow the permission for certain Pages in your crossposting whitelist to crosspost a specific video.

  • POST /{page_id}/crossposting_pages=[{"page_id": {page_id}, "allow": false, "action": "EXPIRE_ALL_CROSSPOSTS_ON_SHARED_ASSETS"}] - Remove pages from your crossposting whitelist and expire all previously crossposted content.

  • POST /{page_id}/crossposting_pages=[{"page_id": {page_id}, "allow": false, "action": "NO_ACTION"}] - Remove pages from your crossposting whitelist without affecting previously crossposted content.


  • GET /{app-id}/subscriptions - This endpoint now returns versions for fields. Before Webhooks versioning was introduced, the endpoint returned only a list of subscribed fields. Now the endpoints return the list of fields with their respective versions.



  • GET /{message-id} - The following field has been deprecated:
    • subject
  • GET /{thread-id} - The following field has been deprecated:
    • tags

90-Day Breaking Changes

  • The following fields are deprecated for edges and dialogs that allow attaching links to posts:

    • caption
    • description
    • name
    • picture
    • thumbnail
  • The edges and dialogs for which these are deprecated include:

    • POST /{event-id}/feed
    • POST /{group-id}/feed
    • POST /{page-id}/feed
    • POST /{user-id}/feed
    • share and feed dialogs


  • Insights Edge - All paid and organic metrics are deprecated.


  • The following Webhooks fields from the user topic are deprecated:

    • about_me
    • birthday_date
    • contact_email
    • current_location
    • education_history
    • hometown_location
    • sex
    • statuses
    • tv
    • work_history
  • Instead use:

    • about
    • birthday
    • education
    • email
    • gender
    • hometown
    • location
    • status
    • television
    • work

Marketing API V2.9

Released April 18, 2017 | Available until November 6, 2017

New Features

Ad Creative

  • Create Canvas campaigns on Facebook through Marketing API. - By using sight, sound, and motion, the video format allows advertisers to effectively drive both brand and direct response objectives. See Marketing API, Canvas Ads.

Dynamic Ads

  • Dynamic Ads Catalog Quality - We are introducing new APIs to help you successfully run Dynamic Ads: Checks and Quality APIs. With Checks API you can verify that your source of signals provide enough information to deliver the right ads with Dynamic Ads. With Quality API, you can check and verify that your catalog and feed have enough information of sufficient quality to deliver Dynamic Ads. For more information, see Dynamic Ads, Catalog and Signals Quality.

  • Multi-Images for Single Item - Show multiple images of the same item in Dynamic Ads in carousel format. We now support up to 20 images from a catalog to represent a single item in the carousel format for Dynamic Ads. This enables you to show a single item such as hotel or destination with multiple images. To support this we offer new options: force_single_link = true and show_multiple_images = true. For details, see Dynamic Ads, Ads Management, Creative Template.

Ads Management

  • Ad Copy - You can now duplicate your existing campaigns, ad sets, and ads using our Ad Copy API's. This way, you don't need to re-create ads from scratch each time; instead, you can duplicate ones that work & create ads template shells. See Ad Creative, Placement, and Preview.

  • Estimated Daily Reach - We have a new endpoint /delivery_estimate at the ad account and ad set levels. This endpoint enables you to get the bid estimates and an outcome prediction with daily reach and conversions for a given ad set. See Targeting, Estimated Daily Reach.

  • Rules Engine API — Use the rules engine API's to manage your ads more easily, efficiently and intelligently, based on business rules that you set. The rules engine uses a push-based model, so instead of having to constantly query our API's to get up-to-date info on your ads, we proactively send you push notifications and perform your specified actions when rule conditions are met. More details about the rules engine API here.

  • Batch API - Group requests and send them asynchronously. Group several Graph API calls into one HTTP request, and execute them asynchronously without having to block. You can also specify dependencies between related operations. Facebook processes each independent operation in parallel processes and your dependent operations sequentially. See Asynchronous and Batch Requests, Batch API.

Ads Placement

  • Effective Ad Placement - You can specify ad placements in the target spec, however you may not have known if Facebook actually delivered your ad to all the placements. If you selected invalid placements for a given objective, Facebook did not deliver on this placement. In the past, you had to run ads and experiment to determine the actual outcome. With the effective_ placement APIs, you can determine the actual ads placements delivered by Facebook for your selected placement and given advertising objective. Through recommendations API, you can also learn why some placements are filtered out. See Targeting, Advanced, Effective Placement.


Ads Management

  • Suggested Video Placement - This was part of Feed placement for Facebook; you opted in to this placement automatically if you used to Feed placement. As of 2.9, we separate Suggested Video placement from the Feed placement so you can opt out of Suggested Video placement even if you opt in to Feed placement. For 2.8 and earlier, if you used Feed placement for Facebook, we will no longer automatically deliver your ads to Suggested Video when you opt in to Feed placement.


Ads Management

  • Local Awareness Objective - We deprecated the campaign objective LOCAL_AWARENESS. As of 2.9 we will not accept LOCAL_AWARENESS as an objective to create new campaigns. Drive local awareness for single location adsets with REACH campaigns. We no longer support LOCAL_AWARENESS for multiple locations. If you have existing campaigns with this objective, you can still read or edit it and you can create new adsets and ads in it. If you copy campaigns from existing campaigns, the type of campaign determines if you can copy it. With LOCAL_AWARENESS single location we copy it with REACH specified. For LOCAL_AWARENESS and multiple locations you cannot copy the campaign.
  • Mobile Ads Objectives - To simplify our mobile ads objectives, the following objectives are deprecated:
    • CanvasAppEngagement, CAE
    • CanvasAppInstalls, CAI
    • MobileAppInstalls, MAI
    • MobileAppEngagement, MAE
  • Instead use:
    • CAE adsets by LINK_CLICKS campaigns, you need to use LINK_CLICKS to create campaigns for CAE ads.
    • MAE adsets with LINK_CLICKS or CONVERSIONS objective campaigns, you need to change to LINK_CLICKS or CONVERSIONS to create campaigns for MAE ads.
    • CAI ad sets with APP_INSTALLS, you should use APP_INSTALLS to create campaigns for CAI ads.
    • MAI with APP_INSTALLS, you should to use APP_INSTALLS to create campaigns for MAI ads.
  • Mobile Ads Objectives, Compatability - When you duplicate CAE, MAE, CAI and MAI campaigns with Marketing API or Facebook tools, we automatically translate these deprecated objectives into their 2.9 equivalents:

    • MAI or CAI campaigns convert to APP_INSTALLS objective.
    • CAE campaigns convert to LINK_CLICKS campaigns.
    • MAE campaigns convert to LINK_LICKS or CONVERSIONS campaigns based on the optimizations you provide for ad sets in the campaign. If there is any child adsets optimized for OFFSITE_CONVERSION, we convert your MAE campaign to a CONVERSIONS campaign, otherwise we translate your MAE campaign to a LINK_CLICKS campaign.
  • Blocked Categories - We are deprecating some Audience Network, Instream Video, and Instant Article categories in favor of more unified categories across these placements. These categories enable you to prevent ads displaying with certain objectionable content, such as gambling, alcohol and so on. The following categories are deprecated:

    • politics
    • religion
  • The following categories are available:

    • For Instant Articles and Audience Network:
      • debated_social_issues
      • mature_audiences
      • tragedy_and_conflict
      • dating
      • gambling
    • For Instream Videos:
      • debated_social_issues
      • mature_audiences
      • tragedy_and_conflict

Ad Creatives

  • SUPPLEMENTAL_MEDIA_ID is deprecated from ad creatives at the ad account and ad levels. You are no longer able to read this field.

  • ACTION_SPEC is deprecated from ad creatives. This was used with sponsored stories which we no longer support.

  • actor_image_hash, actor_image_url and actor_name fields in ad creative are deprecated in 2.9 and 2.8. They were used with action_spec which we also deprecated.

  • link_title and link_description in call_to_action from ad creatives is deprecated. To set titles and descriptions for ad creative, use name and description in link_data, or title and link_description in video_data.

  • run_status=3 - You were able to delete ad creative with this field and value. This caused confusion so we've renamed run_status to status and the value from Int to the String value DELETED. To delete ad creative use status=DELETED.

  • COVER_PHOTO_ID from GET on creative endpoints {creative_id} and {ad_account_id}/adcreatives is deprecated. This was rarely used and available for internal and limited use only.

  • image_url or image_hash - You can now only provide one of these in video_data for ad creative's object_story_spec. See Ad Creative, Reference.

  • OBJECT_INSTAGRAM_ID from GET for creative endpoints is deprecated, including {creative_id} and AD_ACCOUNT_ID/adcreatives. This field was not intended for external use.

  • instagram_story_id was used to fetch Instagram post IDs in ad creative in v2.8 and earlier. If you used this field when you provided ad creative, we threw an exception, but ignored this parameter and passed back results with instagram_story_id. If you used the response, you would get an error. To resolve this issue, we rename instagram_story_id to effective_instagram_story_id and you should not use this field to provide ad creative.

Dynamic Ads

  • No Identical Product Sets - We no longer allow product sets that are identical to another product set from the same catalog. If you try to create an identical product set from the same catalog, our API will return a FacebookApiException with code 10803 containing the ID of the identical product set.

  • quoted_fields in POST /{product_feed_id} deprecated. In v2.6 we removed quoted_fields under POST /{product_feed_id/product_feeds}. As part of additional cleanup we are now also deprecating this.

  • POST {catalog-id}/batch endpoint endpoint now returns STRING as part of ongoing improvements to Dynamic Ads product catalogs.

  • Failure for Audience Updates - If you're using Dynamic Ads and try to update an audience for these ads, your request fails with an error. To make changes, you need to delete the audience associated with your Dynamic Ads and create a new one. See Dynamic Ads, Audiences and Custom Audiences

  • template_url_spec replaces template_url. This enables you to perform click tracking and place context-specific URLs beyond Product Catalog URLs into your Ads. For example, include someone's selected check-in and check-out dates in your ad. See Dynamic Ads, Ads Management.

Signals and Targeting

  • Renaming for Event Sources - In the past, when you created or queryed custom conversions, you used fields labeled pixel_id, pixel_rule and pixel_aggregation_rule. Since we are adding support for offline conversion data and custom conversion data from apps, we are relabeling the fields to express the expanded scope. These fields are now known as event_source_id, rule and aggregation_rule.

  • Conversion Tracking Pixel - This was deprecated February 15, 2017. As part of this, we have removed all edges and nodes for creating, updating, reading, or referencing the Conversion Tracking Pixel for all versions of the API.

  • friends_of_connection associated with event IDs is deprecated as an ads targeting option. This means you cannot target friends of people who accepted your Facebook event invitation.

  • delivery_estimate Support - We made Reach Estimate changes to support the newly launched delivery_estimate:

    • Removed bid_estimations field from /reach_estimates endpoint and moved all of the documented functionality over to /delivery_estimate

    • /AD_ID/reachestimate has been deprecated. To access this information use /ADSET_ID/delivery_estimate.

    • Removed the data field.


  • date_preset Deprecations - We are deprecating several date_preset values which we are replacing with new values. The new values are designed to be easier to use and in alignment with advertiser expectations, and will no longer include data from the current day. For example, a request made on Feb 8th and using "the last 7 days" date range preset will result in a report that encompasses Feb 1 through 11:59 p.m. on Feb 7 inclusive, and excludes Feb 8th. These values are deprecated:

    • last_3_days, replaced by last_3d

    • last_7_days replaced by last_7d

    • last_14_days replaced by last_14d

    • last_28_days replaced by last_28d

    • last_30_days replaced by last_30d

    • last_90_days replaced by last_90d

    • last_week replaced by last_week_sun_sat and last_week_mon_sun

    • this_week replaced by this_week_sun_today and this_week_mon_today

    • last_3_months has been deprecated.

    • For version 2.8 and earlier, we support both these new values and the old date preset values.

  • Default date_preset - If you made an Insights query without date_preset we defaulted to last_30_days which included activity from today from 12:00AM in an ad account's timezone. As of 2.9 this defaults to last_30d. This includes the complete previous 30 days, ending at 11:59 PM last night, in your account's time zone, and not including today.

  • video_complete_watched_actions is deprecated. It provided the same information as video_30_sec_watched_actions.

  • unique_impression and unique_social_impressions are deprecated. Please use reach and social_reach instead.

  • newsfeed_clicks, newsfeed_impressions, newsfeed_avg_position, video_avg_sec_watched_actions, video_avg_pct_watched_actions are outdated metrics being deprecated.

  • The following are deprecated under action_type:: follow, gift_sale, video_play, and vote.

  • click_to_play_video is now accessible via the action_video_type breakdown.

  • placement breakdown field for delivery data is deprecated from Insights API. Only ["publisher_platform", "platform_position"] are supported in 2.9. In 2.8, we still support both ["placement"] or ["publisher_platform", "platform_position"] as breakdowns.

  • attribution_spec - In the past, you used two separate fields for click-through and view-through attribution windows in Insights API. You should now use attribution_spec to set both of them. When you set attribution_spec you override any existing settings. If you had set both click-through and view-through, when you set attribution_spec to event_type = CLICK_THROUGH you only remove view-through attribution.

90-Day Breaking Changes

No 90-Day Breaking Changes.

Version 2.8

Graph API | Marketing API

Changelog entries are categorized in the following way:

  • New Features — New products or services, including new nodes, edges, and fields.
  • Changes — Changes to existing products or services (not including Deprecations).
  • Deprecations — Existing products or services that are being removed.
  • 90-Day Breaking Changes — Changes and deprecations that will take effect 90 days after the version release date.

New Features, Changes, and Deprecations only affect this version. 90-Day Breaking Changes affect all versions.

Breaking Changes are not included here since they are not tied to specific releases.

Graph API v2.8

Released October 5, 2016 | Available until April 18, 2019

New Features v2.8

Open Graph Actions

  • Two new common Open Graph action types, available to all developers in all versions of the API, have been added:

    • books.rates
    • games.plays

Resumable Upload API

  • Upload files a small piece at a time, allowing for more reliability over poor connections. Please see our guide on the Resumable Upload API for more information. This API is only available for page thumbnails right now, but will expand to other types of media in the future (like video).


  • ThreatExchange has some new features, including support for Webhooks and new tagging functionality. Please see the ThreatExchange Changelog for more information.

Changes v2.8


  • Feed Targeting - The targeting and feed_targeting fields on the /page/feed edge now consistently use geo_locations instead of specifying geography via other methods. See our guide on targeting which includes information about the geo_locations object.

Deprecations v2.8

Open Graph

  • Custom Open Graph Actions - Apps can no longer create new Open Graph action or object types or publish Open Graph Stories that use custom action or object types. Approximately 1 year after the v2.8 release, no version of the API will allow publishing stories that use custom action or object types. Please see our deprecation guide for more information.

  • Open Graph Stories - Localization is no longer supported.


  • /admined_groups - This edge on the User node has been deprecated. Use groups edge on the User node instead.

  • bio - This field on the User node has been deprecated. Use the about field instead.

90-Day Breaking Changes v2.8

Open Graph

  • Custom Open Graph Actions

    • No versions of the API will allow the creation of new Open Graph action or object types.
    • All App Collections will be removed from people's profiles.
    • Please see our deprecation guide for more information.

Version 2.7

Graph API | Marketing API

Changelog entries are categorized in the following way:

  • New Features — New products or services, including new nodes, edges, and fields.
  • Changes — Changes to existing products or services (not including Deprecations).
  • Deprecations — Existing products or services that are being removed.
  • 90-Day Breaking Changes — Changes and deprecations that will take effect 90 days after the version release date.

New Features, Changes, and Deprecations only affect this version. 90-Day Breaking Changes affect all versions.

Breaking Changes are not included here since they are not tied to specific releases.

Graph API v2.7

Released July 13, 2016 | Available until October 5, 2018

New Features v2.7


  • Metrics - The following metrics have been added. These counts include breakdowns by organic, paid, source, and time and lifetime breakdown by user demographic info.

    • follow
    • unfollow
  • Webhooks The following field has been added:

    • is_webhooks_subscribed - Returns the status of a Webhooks subscription from the Page node. This field can be retrieved via GET or updated with a POST on /{page-id}.


  • Geotargeting Support - We now support geotargeting and gating via the targeting param on POST /{video-id} and POST /{page-id}/live_videos. This can also be extended to supporting restrictions by excluded locales through the API.

  • Video Node Fields - The following fields have been added to the Video node:

    • copyright_monitoring_status
    • feed_type

Changes v2.7

Business Manager API

  • Permissions: Your app now needs the business_management extended permission to access Business Manager. ads_management or the manage_pages permissions will no longer allow access. Facebook will migrate existing apps with these permissions to the new permission. Apps using this permission for the first time need to go through review. Please see Permissions and Business Manager API, Prerequisites for more information.


  • GET /{page-id}/tagged - This edge now returns posts in which the Page has been tagged. This is a change in behavior from previous versions that only returned posts directed to the Page.

  • Page Insights - Page metrics insights must now be explicitly specified when making Page Insights related requests. The default behavior of returning all metrics when none are specified is no longer supported.

Deprecations v2.7

  • No deprecations.

90-Day Breaking Changes v2.7

Open Graph

  • GET /{open-graph-object-id}/ - The url field has been removed from this node.

Version 2.6

Graph API | Marketing API

Changelog entries are categorized in the following way:

  • New Features — New products or services, including new nodes, edges, and fields.
  • Changes — Changes to existing products or services (not including Deprecations).
  • Deprecations — Existing products or services that are being removed.
  • 90-Day Breaking Changes — Changes and deprecations that will take effect 90 days after the version release date.

New Features, Changes, and Deprecations only affect this version. 90-Day Breaking Changes affect all versions.

Breaking Changes are not included here since they are not tied to specific releases.

Graph API Version 2.6

Released April 12, 2016 | Available until July 13, 2018

New Features


  • Notes on Users - Page admins can take notes on Users. Please see the admin_notes edge reference docs on the Page node for more information.
  • Labels on Users - Page admins can create labels for Users. Please see the labels edge reference docs on the User node for more information.
  • Send Messages to Users Using Page-Scoped ID or Phone Number - Pages can now send text, attachments, and template messages to users through their page-scoped-ids or phone numbers.
    • The pages_messaging permission to send and receive messages on behalf of a Page.
    • The pages_messaging_phone_number permission to send messages on behalf of Pages using a phone number as an ID.

Video APIs

  • Live API - Post and manage Live Videos. Access to these endpoints requires approval. Please see our Live API documentation for more information.

  • Video Node - The following fields have been added. Please see the Video node reference docs for more details.

    • live_status. The current broadcast state of the video. Values include: LIVE, LIVE_STOPPED, VOD. If this field is null, it means the video was never broadcast.
    • live_audience_count - The number of unique viewers who watched the video when it was live.
    • content_tags - Add tags to a video.
  • Rights Manager API - We've introduced a new Rights Manager API that allows a copyright owner to claim ownership for videos and manage copyright matching rules. To use the API, please enroll via the Rights Manager Enrollment website. Please see our documentation for the Rights Manager API for more information about the API and the enrollment process.
  • Crossposted Videos - Pages can now create posts from videos they own without the need to re-upload the videos again. The major benefit of this is that you can see consolidated insights for a video and a breakdown of metrics across the multiple posts created from the video. Please see the is_crossposting_eligible and crossposted_video_id field in the Video node and the videos_you_can_use field on the Page node for more information. The videos_you_can_use field tells you if a Page owner has granted permission for you to cross-post it
  • Video Insights - The following edge has been added to the Video node:

    • video_insights - Contains aggregated video insights from all crossposts across Pages. See the video_insights edge for more information. We have also added Daily Video Metrics, Minutes Watched, and 10s metrics to insights edge on the Post Node.

Messenger APIs

  • Webhooks - The following fields have been added. Please see our implementation guide for more information.

    • messages - Receive inbound messages.
    • message_deliveries - Receive delivery confirmations.
    • messaging_optins - Receive authentiation events.
    • messaging_postbacks - Receive postback from buttons on Structured Messages.
  • Messenger Plugin - We've added a new web plugin to authenticate people into the Messenger Platform. People can now interact with your business over Messenger. Please see our implementation guide for more information.

  • Message Us Plugin - We've added a new web plugin to enable people to start a chat directly with a Page. Please see our implementation guide for more information.

  • Send/Receive API - The Send/Receive API is part of the Messenger Platform. It can be used to send and receive messages between people and Pages. Please see our implementation guide.

Sharing for Devices

  • Sharing for Devices - We're launching a new Sharing for Devices API that lets you share easily from a device to Facebook. Please see our documentation on Sharing for Devices for more information.


  • Reactions API - We've added a new reactions edge for objects that were previously likable. As an example, please see the Photo edge for reactions.



  • The likes field on the Page node has been renamed to fan_count.
  • You can no longer login as a Page. Please see our Pages documentation to learn more about posting as a Page.


6 Month Deprecations

  • Feed Dialog - Applications using the Feed Dialog will be required to have the publish_actions permission to have access to the returned post_id. The post_id will only be returned if the share generates a story on a person's timeline or in a group. This will take effect on October 11th.


  • Insights - The following metric has been deprecated:

    • facebook_login_total_users


  • Device Authentication - The following endpoint has been deprecated:

    • oauth/device - This affects devices that use this endpoint to generate access tokens. Please use the device/login and device/login_status endpoints instead. See our documentation on logging in with devices for more information.


  • The following Pages Insights have been deprecated. Each of these has been replaced by another way to query a similar set of insights. Please see our documentation on Page Views for more information. The new insights start with the page_views prefix.

    • page_visits_by_age_gender_logged_in_unique
    • page_visits_by_internal_referer_logged_in_unique
    • page_visits_by_profile_tab_logged_in_unique
    • page_visits_by_profile_tab_total
    • page_visits_by_site_logged_in_unique
    • page_visits_logged_in_total
    • page_visits_logged_in_unique
    • page_visits_total

Breaking Changes


  • Role Visibility - Starting with the release of v2.6, an application can no longer see all of the roles that a developer has on other apps. This change also applies to previous versions.


  • Game Groups Beta - The Game Groups Beta feature, also known as App Groups, is deprecated as a 6 month deprecation. Effective May 1, no new apps may use the Game Groups API. Final deprecation effective on October 18th.

90-Day Breaking Changes


  • Rate Limits Changes for Page-related Requests - If you make a request with a Page Access Token, the limits will scale with the number of people engaging with the page. This change will take effect July 11th.


  • All Callback Subscriptions Must Use HTTPS - When we launched Graph API v2.5 last October we began requiring new Webhooks (formerly known as Real Time Updates) subscriptions to be configured for HTTPS. With v2.6, this is now required for all new Dynamic Pricing and Deauthorization endpoints as well. Beginning 90 days from today, we will require all callback subscriptions to be configured for HTTPS. At that point, we will stop sending updates to non-HTTPS endpoints, regardless of when they were created. This applies to Webhooks, Webhooks for Payments, Dynamic Pricing, and Deauthorization. You can update your subscriptions on your app dashboard.

Version 2.5

Graph API | Marketing API

Graph API V2.5

This version expired April 12, 2018. Please use the API Upgrade Tool to upgrade your apps before this date. Learn more about upgrading your apps in the Upgrade Guide.

New Features


  • Permissions

    • GET {user_id}/accounts now requires either manage_pages or pages_show_list; the latter is a new permission in v2.5.
    • POST {page_id}/call_to_actions and POST/DELETE {call-to-action-id} require the new permission pages_manage_cta that we introduce in v2.5.
  • Managing Call-to-Actions - Pages can now manage call to actions on a Page:

    • GET page/call_to_actions or GET {call-to-action-id} to read a call to action.
    • POST page/call_to_actions to add a call to action to a page.
    • POST {call-to-action-id} to update.
    • DELETE {call-to-action-id} to delete a Page's call to action.
  • Place Node - The following field has been added to the Place node:

    • overall_rating - This provides the average rating based on public reviews of a place.


  • Video Upload - The following parameters have been added:

    • slideshow_spec - Generate slide show videos by uploading images.
    • secret - Published video will not appear on Facebook Newsfeed, Timeline, or Page video tabs and is not searchable. A video can be viewed and shared using a permalink only. For page users only.
    • social_actions - Enable or prohibit the use of Facebook social actions such as likes, comments, and sharing on an hidden video. For page users only.
  • Video Editing - The following parameters have been added:

    • publish_to_videos_tab - Distribute video items publicly to the Page's Videos tab, but not News Feed or Timeline.
    • publish_to_news_feed - Distribute video items publicly to News Feed, Page Timeline, and a Page's Videos tab.



  • Tagged Posts Endpoint - GET /{page-id}/tagged will include all public posts in which the page has been tagged. A page access token with manage_pages permission is required.


  • story_tags - Now returns an array, not an object.


  • GET /{user-id}?fields=address returns an error - The address field, which was available in previous versions and returned an empty value, will return an error as of v2.5.

Webhooks (Formerly Real Time Updates)

  • Automatically Disable Subscriptions - We now automatically disable Webhooks subscriptions if the callback URL fails for 7 days straight. You can re-enable it with a POST request to /subscriptions. This change does not apply to payments subscriptions.

  • Updating Existing Subscriptions - Existing Webhooks subscriptions may be modified via the /subscriptions API. POST /subscriptions will amend the subscription for the given topic without overwriting existing fields. You can delete specific fields from your subscription by including a fields param when calling DELETE /subscriptions.


  • No deprecations.

90 Day Breaking Changes


  • Page Tab Apps URI Format - Page Tab Apps URI format{vanity}?v={app_id} will no longer work 90 days after this release. Please use{vanity}?sk={app_id} or{vanity}/{app_id}.


  • New Real Time Updates via HTTPS Only - New subscriptions cannot be created with a non-HTTPS callback URL. This affects User, Page, App, and Payment updates.

Version 2.4

Graph API | Marketing API

Graph API V2.4

Released July 8th, 2015 | No longer available

New Features

Page Video Insights

In v2.4 we expose a set of new Page Video metrics, such as page_video_views_paid, page_video_views_autoplayed, and page_video_views_organic available from the Graph API via GET /v2.4/{page_id}/insights/?metric={metric}. These metrics require the read_insights permission.

New Video Features

The Video node now contains the following fields in GET|POST operations to /v2.4/{video_id}:

  • content_category which supports categorizing a video during video upload, and can be used for suggested videos. Content categories include: Business, Comedy, Lifestyle, etc and a full list of categories can be viewed on the Video node docs page.
  • unpublished_content_type will expose 3 new types (Scheduled, Draft, and Ads_Post) which will help coordinate how the video is posted.
  • expiration and expiration_type allows the video expiration time to be set, along with the type (hide, delete).
  • embeddable boolean flag is now available to control if 3rd party websites can embed your video.

Accessing Timeline Posts

We've simplified how you access content on a person's Timeline. Instead of handling different object types for statues and links, the API now returns a standardized Post node with attachments which represent the type of content that was shared. For more details view the User reference docs.

Marketing API

For Marketing API (formerly known as Ads API) v2.4 new features.


Permission related changes

  • Operations that reference the admin_creator object of a Post in now requires a Page access token.
  • POST /v2.4/{page_id}/offers and DELETE /v2.4/{offer_id} now require a Page access token with manage_pages and publish_pages permissions.
  • GET /v2.4/{page_id}/milestones, POST /v2.4/{milestone_id}, and DELETE /v2.4/{milestone_id} now require a Page access token with manage_pages and publish_pages permission.

Changes to Pages APIs

  • Calls made to the Page node GET /v2.4/{page_id}/promotable_posts now require a user access token with ads_management permission or a Page access token.
  • The global_brand_parent_page object has been renamed to global_brand_root_id.
  • GET /v2.4/{global_brand_default_page_id/insights will now return only insights of the default Page insight data, instead of the insights for the Global Brand hierarchy. Use the Root Page ID to retrieve the integrated insights of the whole hierarchy.
  • GET|POST /v2.4/{page_id}/promotable_posts has renamed the field is_inline to include_inline.
  • The maximum limit for Page related objects is now set to limit=100. This will impact GET operations made on the feed, posts, and promotable_posts edges.

Event Ordering

The default pagination ordering of GET {user-id}/events now begins with the newest event first, and is ordered in reverse chronological order.

Improved Filtering

Graph API v2.4 now supports filtering of GET /v2.4/{user_id}/accounts with new boolean fields:

  • is_promotable filter results by ones that can be promoted.
  • is_business filter results associated with a Business Manager.
  • is_place Include Place as results filter.

Declarative Fields

To try to improve performance on mobile networks, Nodes and Edges in v2.4 requires that you explicitly request the field(s) you need for your GET requests. For example, GET /v2.4/me/feed no longer includes likes and comments by default, but GET /v2.4/me/feed?fields=comments,likes will return the data. For more details see the docs on how to request specific fields.


2-year deprecations

  • GET /v2.4/{id}/links and GET /v2.4/{id}/statuses will no longer be available beginning in v2.4. As an alternative, we suggest using GET /v2.4/{id}/feed.
  • GET|POST /v2.4/{page_id}/?fields=global_brand_parent_page is being deprecated in this version and replaced by /v2.4/{page_id}/?fields=global_brand_root_id.
  • GET|POST /v2.4/{page_id}/global_brand_default_page_id/global_brand_children will no longer function in v2.4. As an alternative, please use the root page ID.
  • GET /v2.4/{page_id}/promotable_posts will no longer support the filter and type params in v2.4. For example, a call to GET /v2.4/{page_id}/promotable_posts?type=STATUS will return an empty result set.
  • The Event node no longer supports GET operations on the endpoints /v2.4/{event_id}/invited, /v2.4/{event_id}/likes, or /v2.4/{event_id}/sharedposts.

90-day deprecations (effective Tuesday, October 6, 2015)

  • The GET /v2.4/{user_id}/home, GET /v2.4/{user_id}/inbox, and GET /v2.4/{user_id}/notifications operations as well as read_stream, read_mailbox, and manage_notifications permissions are deprecated in v2.4.
  • the user_groups permission has been deprecated. Developers may continue to use the user_managed_groups permission to access the groups a person is the administrator of. This information is still accessed via the /v2.4/{user_id}/groups edge which is still available in v2.4.
  • GET /v2.4/{event_id}/?fields=privacy is deprecated in v2.4.
  • GET /v2.4/{event_id}/?fields=feed_targeting is deprecated in v2.4.
  • GET /v2.4/{event_id}/?fields=is_date_only is deprecated in v2.4.

From October 6, 2015 onwards, in all previous API versions, these endpoints will return empty arrays, the permissions will be ignored if requested in the Login Dialog, and will not be returned in calls to the /v2.4/me/permissions endpoint.

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.

Version 2.3

Graph API | Marketing API

Graph API V2.3

Released March 25th, 2015 | No Longer available

New Features

  • user_posts Permission - We have a new permission user_posts that allows an app to access the posts on a person's Timeline. This includes the someone's own posts, posts they are tagged in and posts other people make on their Timeline. Previously, this content was accessible with the read_stream permission. The user_posts permission is automatically granted to anyone who previously had read_stream permission.

  • all_mutual_friends Edge - This Social context edge enables apps to access the full list of mutual friends between two people who use the app. This includes mutual friends who use the app, as well as limited information about those who don't.

Both users for whom you're calling this endpoint must have granted the user_friends permission.

If you calling this endpoint for someone not listed in your app's Roles section you must submit your app for review by Facebook via App Review.

Although this edge is new to Graph API v2.3, to make it easier for you to migrate we also added this edge to v2.0, v2.1, and v2.2.

  • Debug Mode - Provides extra information about an API call in the response. This can help you debug possible problems and is now in Graph API Explorer, as well as the iOS and Android SDKs. For more information see Graph API Debug Mode.

  • New Pages Features

  • Real-time Updates - As of March 25, 2015 We now send content in Page real-time updates (RTUs). Previously, only the object's ID was in the RTU payload. Now we include content in addition to the ID including: statuses, posts, shares, photos, videos, milestones, likes and comments. In order for the app to receive these types of updates, you must have enabled the "Realtime Updates v2.0 Behavior" migration in your app's dashboard.

  • Page Reviews now support real-time updates. Apps can subscribe to the ratings property to receive a ping every time a public review is posted on pages the app is subscribed to. In order for the app to receive this type of update, you must have enabled the "Realtime Updates v2.0 Behavior" migration in your app's dashboard.

  • Page Posts, admin_creator - All Page Posts now include a new admin_creator field that contains the id and name of the Page Admin that created the post. This is visible when you use a Page access token, or the user access token of a person who has a role on the Page.

  • New Page Fields -GET|POST /v2.3/{page-id} now supports fetching and updating these fields: emails, food_styles, public_transit, general_manager, attire, culinary_team, restaurant_services, restaurant_specialties, and start_info.

  • New Page Settings - GET|POST /v2.3/{page-id}/settings now supports four new settings: REVIEW_POSTS_BY_OTHER, COUNTRY_RESTRICTIONS, AGE_RESTRICTIONS, and PROFANITY_FILTER.

  • Larger Videos with Resumable Upload - We now support larger video sizes uploads up to 1.5GB or 45 minutes long with resumable video upload. See Video Upload with Graph API.
  • File URL Parameter - At all /v2.3/{object_id}/videos edges you can create a new Video object from the web by providng the file_url parameter.
  • Resumable, Chunked Upload - All /v2.3/{object_id}/videos edges support resumable, chunked uploads. For more information, see Video Upload with Graph API.
  • Video Playlists - You can now create and manage video playlists for Pages by using GET|POST|DELETE on the /v2.3/{page_id}/videolist edge. you can also add videos to a playlist by POST /v2.3/{videolist_id}/videos and GET the videos of a playlist.

  • Page's Featured Video - You can now set and get the featured_video of a page using GET|POST /v2.3/{page_id}/featured_videos_collection.

  • Publish Fields - All Video nodes objects at /v2.3/{video_id} now return the new fields: published, a boolean which indicates if the video is currently published, and scheduled_publish_time.

  • Custom Thumbnail - You can now upload and manage custom video thumbnails as JPEGs or PNGs with GET|POST /v2.3/{video_id}/thumbnail. See Graph API Reference, Video Thumbnail.

  • Targeting Restrictions - POST /v2.3/{page-id}/videos now supports targeting restrictions by country, locale, age range, gender, zipcode, timezone and excludin locations.

  • Delete - DELETE /v2.3/{video_id} removes videos. This is supported if you have edit permissions on the video object.

  • New Read and Write Fields - The Video node now supports retrieving and modifying additional fields: backdated_time, and backdated_time_granularity.

  • Subtitles, Localized Captions - GET|POST /v2.3/{video-id} now supports supplying and retrieving subtitles and localized captions.

  • Visibility of Video - With POST /v2.3/{page_id}/videos you can control where the video is seen with no_story and backdated_post.hide_from_newsfeed parameters. These parameters target visibility on feeds and page timelines.

Marketing API V2.3

Formerly known as Ads API v2.3

Changes from v2.2 to v2.3

  • Page Plugin - Is the new name for Like Box Social Plugin and it has a new design.

  • Comments Plugins Has a new design and it now supports Comment Mirroring (private beta).

  • Requests are now GameRequests - Previously this term and object-type created confusion for non-game app developers, and the intended usage of these objects are to invite others to a game Non-game apps should use App Invites. The /v2.3/{user-id}/apprequests edge is now limited to game apps. See Games, Requests.

  • read_custom_friendlists - Is the new name for read_friendlists Login permission. This is to clarify that the permission grants access to a person's custom friendlists, not the full list of that person's friends.

  • Changes to Page APIs:

  • publish_pages Permission - This new permission is required to publish as a Page. Previously publish_actions was required. People who granted manage_pages and publish_actions before v2.3 have automatically been granted publish_pages. If anyone logs in via v2.3, you'll need to request publish_pages explicitly in addition to manage_pages.

  • Page Publish Operations - now accept the type of access token the requests are made with. This includes publishing posts, likes and comments. When a user access token of a Page admin is in the request such as POST /v2.3/{page-id}/feed, the action occurs with the voice of the user, instead of the Page. To publish as the Page, you must now use the Page access token.

  • Removing Comments on Page posts - As a Page admin with DELETE /v2.3/{comment-id} now requires a Page access token.

  • POST /v2.3/{page-id} - Now requires country as sub-parameter if you update the location field without specifying the city_id sub-parameter. The state sub-parameter is also required if country sub-parameter is 'United States'.

  • Countries - The country subfield of the feed_targeting field on a Page post is renamed countries when you make a POST|GET /v2.3/{page-id}/{post-id}.

  • Page Field Updates - POST /v2.3/{page-id} - Now supports complete field updates for: hours, parking, payment_options.
    Previously, the update behavior on these fields was to replace a specific key/value pair that was specified as part of the POST, leaving all other keys intact, but the new functionality of a POST on one of these fields will replace all key/value pairs with what is posted.

  • Premium Video Metrics - Insights for Page Premium Video Posts are now deprecated.

  • page_consumptions_by_consumption_type insight now returns data for a local page instead of a parent - In earlier versions of the insights API for a Page, asking for this insight would return data for a parent of a local page. In v2.3, we now return the data for only that local page.

  • Picture Error - For the Link, Post, Thread, Comment, Status, and AppRequest nodes, and other nodes which don't have a picture, the /v2.3/{object}/picture edge now returns an error message. Before, the API returned a placeholder image of a 'question mark' for the picture edge requested on these nodes.

  • [Oauth Access Token] Format - The response format of returned when you exchange a code for an access_token now return valid JSON instead of being URL encoded. The new format of this response is {"access_token": {TOKEN}, "token_type":{TYPE}, "expires_in":{TIME}}. We made this update to be compliant with section 5.1 of RFC 6749.

  • Consistent Place Data - Content objects tagged with a place now share a consistent place data structure which contains the ID, name, and the geolocation of the place. This includes Events, Photos, Videos, Statuses and Albums. As a result, the venue and location fields have been removed from the Event node. Developers should access the place field instead.

In addition, if someone tags a Photo, Video, Status, or Album at an event, that object will contain an event field.

  • Serialized Empty Arrays - All Graph API endpoints now consistently serialize empty arrays as [] and empty objects as {}. Previously, some empty objects were incorrectly serialized as empty arrays.

  • Default Result Limit - All edges will now return 25 results per page by default when the limit param is not specified.

  • Ads API now Marketing API - We recently renamed the Facebook Ads API to the Facebook Marketing API. For details on Marketing API changes see the Marketing API v2.3 Changelog.

90-day deprecations (effective Tuesday, June 23, 2015)

  • Edges and Permissions - /v2.3/{user_id}/interests and /v2.3/{user_id}/activities edges as well as user_interests and user_activities permissions are deprecated in v2.3.

From June 23, 2015 onwards, in all previous API versions, these endpoints will return empty arrays, the permissions will be ignored if requested in the Login Dialog, and will not be returned in calls to the /v2.3/me/permissions endpoint.

  • Page RSS Feed endpoint - at is now deprecated and will stop returning data from June 23, 2015. Developers should call the Graph API's /v2.3/{page_id}/feed endpoint instead. This returns JSON rather than RSS/XML.

  • Social Plugins - The following are now deprecated and will no longer render after June 23, 2015:

  • Facepile Plugin
  • Recommendations Feed Plugin
  • Activity Feed Plugin
  • Like Box Social Plugin

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

Version 2.2

Graph API | Marketing API

Graph API V2.2

Released October 30th, 2014 | No longer Available

New Features

  • Developers may now hide and unhide comments on a Page Post via the Graph API: POST /v2.2/{comment_id}?is_hidden=true to hide, POST /v2.2/{comment_id}?is_hidden=false to unhide. You can determine if a comment is hidden, or if you have the ability to hide/unhide the comment by checking the is_hidden or can_hide fields on the comment node.
  • A new token_for_business field makes it easier to identify the same person across multiple apps owned by the same business: In addition to the Business Mapping API, there is now a new token_for_business field on the user object. This emits a token which is stable for the same person across multiple apps owned by the same business. This will only be emitted if the person has logged into the app. For games developers, this property will also be emitted via the signed_request object passed to a canvas page on load. Note that this is not an ID - it cannot be used against the Graph API, but may be stored and used to associate the app-scoped IDs of a person across multiple apps. Also note that if the owning business changes, this token will also change. If you request this field for an app which is not associated with a business, the API call will return an error.
  • The comment node has a new object field which emits the parent object on which the comment was made. To get the ID and owner of the comment's parent object (for example, a Page Post) you might call: /v2.2/{comment_id}?fields=object.fields(id,from)
  • The Page node has a new edge to manage subscriptions for realtime updates.
  • In previous versions, any app which was added as a Page Tab also received realtime updates. From v2.2 onwards there is a dedicated endpoint for managing these subscriptions:
    • GET /v2.2/{page-id}/subscribed_apps returns the apps subscribed to realtime updates of the Page. This must be called with a Page Access Token.
    • POST /v2.2/{page-id}/subscribed_apps subscribes the calling app to receive realtime updates of the Page. This must be called with a Page Access Token and requires the calling person to have at least the Moderator role on the Page.
    • DELETE /v2.2/{page-id}/subscribed_apps stops the calling app from receiving realtime updates of the Page. This may be called with a Page or App Access Token. If called with Page Access Token, it requires the calling person to have at least the Moderator role on the Page.
  • The feed_targeting parameter is now supported when publishing videos to a Page: POST /v2.2/{page_id}/videos?feed_targeting={targeting_params}. This lets you specify a number of parameters (such as age, location or gender) to help target who sees your content in News Feed. This functionality is already supported on POST /{page_id}/feed so we're extending this to videos too.
  • The Page node has a number of new writeable fields to let apps update a Page's information: The following fields are now supported with POSTing to /v2.2/{page_id}:
  • payment_options takes an object which lets you specify the payment options accepted at the place.
  • price_range accepts an enum of strings which represent the self reported price range of the Page's business.
  • latitude and longitude can now be specified as properties of the location field in order to let apps programmatically update Page's physical location. Both are floats.
  • ignore_coordinate_warnings (boolean) determines if the API should throw an error when latitude and longitude are specified in location field for updating the Page's location. If set to false, an error will be thrown if the specified coordinates don't match with the Page's address.
  • is_always_open lets apps set the status of the place to “Always Open”. This can only be set to true, and will clear previously specified hours in hours field. To set specific hours, use hours field.
  • is_published takes a boolean which lets you publish or unpublish the Page. Unpublished pages are only visible to people listed with a role on the Page.
    • The Page node has a new readable field to let apps read a Page's information: The following field are now supported with a GET to /v2.2/{page_id}:
  • name_with_location_descriptor returns a string which provides additional information about the Page's location besides its name.
    • There's a new APPEARS_IN_RELATED_PAGES setting on /v2.2/{page_id}/settings. This boolean determines if your page can be included in the list of suggested pages which are presented when they like a page similar to yours. You may set or read this value.
    • You can now read the permissions your app has been approved for via an API. A new edge on your App object, called /{app-id}/permissions, allows you to view the permissions that your app has been approved for via Login Review.


  • There's now a limit of 50 IDs which can specified in a single request using the syntax ?ids=ID1,ID2. This reduces the likelihood of timeouts when requesting data about a large number of IDs in a single request.
  • The blocked edge on the Page node now requires a Page Access Token - this endpoint can no longer be called with an App or User token. That endpoint is available at: GET|POST|DELETE /v2.2/{page_id}/blocked?access_token={page_access_token}.
  • The tabs edge on the Page node now requires a Page token for GETs. POSTs and DELETEs on this endpoint already require page tokens. That endpoint is available at: GET|POST|DELETE /v2.2/{page_id}/tabs?access_token={page_access_token} Calling GET on this edge now works for people in the 'Analyst' role. It previously required the 'Editor' role.
  • The tabs edge on the Page node will now throw an error if the caller does not have permission. Previously it would only return an empty string.
  • The /{page_id}/admins edge on the Page node has been renamed to /v2.2/{page_id}/roles. In addition, in the response, the values returned in the role field have been changed:
  • MANAGER has been renamed to Admin.
  • CONTENT_CREATOR has been renamed to Editor.
  • MODERATOR has been renamed to Moderator.
  • ADVERTISER has been renamed to Advertiser.
  • INSIGHTS_ANALYST has been renamed to Analyst.
  • The settings edge on the Page node will no longer include entries for settings where the value field would be null.
  • POST /{page_id}/settings will no longer support the setting and value params. Instead, you should specify the option param which should be an object containing a single key/value pair with the setting enum as the key.
  • From v2.2 onwards, apps calling GET /v2.2/{page_id}/notifications must use a Page Access Token. Previously this required the manage_notifications permission. User Access Tokens will no longer work for this endpoint.
  • The structure of the /v2.2/{group_id}/albums endpoint has changed to match the response of /{user_id}/albums.
  • The number of results returned from the /v2.2/me/friends endpoint now defaults to 25.

90-day deprecations (effective Wednesday, January 28, 2015)

  • The fb:name social plugin has been deprecated and will stop working on Jan 28, 2015. Developers should instead use the FB.api() method of the Javascript SDK to retrieve the names of users.
  • In versions previous to v2.2, it was possible for an app to see if a person like the app's page by checking the page_fan FQL table or the /{user_id}/likes/{app_page_id} Graph API endpoint without needing the user_likes permission. Starting in v2.2, the user_likes permission will be required to query these endpoints. Also, we will require the user_likes permission on versions older than v2.2 starting 90 days from today, on Jan 28, 2015. Facebook will not grant the user_likes permission solely for the purpose of checking if a person has liked an app's page. This change was announced on August 7, 2014 and will come into effect on November 5, 2014.
  • The Pages JSON feed (e.g. is now deprecated and will stop returning data from Jan 28, 2015 onwards. Developers should instead call the feed edge on the Graph API's Page object: /v2.2/{page_id}/feed.
  • POST /{page-id}/tabs and DELETE /{page-id}/tabs will no longer support subscribing or unsubscribing an app for realtime updates. This will take effect in all previous API versions on January 28, 2015. To subscribe an app to realtime updates for a page, use the new /v2.2/{page_id}/subscribed_apps endpoint.
  • The Comments Plugin will no longer support commenting via third-party identifiers after January 28, 2015. This facility was rarely used and the majority of comments posted by these accounts were of low quality. People may still comment using their Facebook account, or may also comments as a Facebook Page.

Disabled SSL 3.0 Support

On October 14, 2014, we dropped support for SSL 3.0 across Facebook properties, including the Facebook Platform API and the Real-Time Updates API, after a vulnerability in the protocol was revealed on October 14, 2014. This change helps protect people’s information.

If your HTTP library forces the use of SSL 3.0 rather than TLS, you will no longer be able to connect to Facebook. Please update your libraries and/or configuration so that TLS is available.

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.

Version 2.1

Graph API V2.1

Released August 7, 2014 | No longer Available

This is Facebook's first new API update after version 2.0 was launched at the 2014 f8 conference. API versions are supported for two years after the next version is released. This means that:

  • Version 2.1 will be available starting today until two years after the release of a post-v2.1 version.
  • Version 2.0 will expire on August 7, 2016, two years after the release of v2.1. (Version 2.0 was introduced on April 30, 2014.)
  • Version 1.0 will expire as scheduled on April 30, 2015.

New Features

  • Pages can mention other Pages when publishing via API: When making calls to several Page publishing edges such as /feed or /photos you can now mention other Pages in a message field. This extends our current availability of mentions in Open Graph. This API requires review by Facebook before it can be used by people other than the app’s developers. Learn more about the Page Mentions review process in our documentation.
  • New total friend count on the friends connection: /v2.1/me/friends (and /v2.0/me/friends) now provides access to total friend count - this count includes friends who use the app as well as those who don't.
  • New 'facebook-api-version' HTTP header: In all API versions, we now return an HTTP response header called 'facebook-api-version' which indicates which API version your app is actually experiencing - this may be different to the API version you specify in your request due to upgrades.
  • New App Insights API: v2.1 includes access to the new App Insights data via an API. This is available by calling /v2.1/{app_id}/app_insights
  • A new format for Graph API Field Expansion: v2.1 introduces more concise syntax for Field Expansion. (The new syntax is also been added to v2.0 and earlier). See our documentation on field expansion for examples. The older format for field expansion is still available, but the new format is preferred.
  • User-facing error messages: In some cases (such as access token invalidation or expiry) the API now returns user-displayable error messages which describe the error and what the person may need to do to resolve it. These error messages will be returned in US English by default, but if you query the Graph API specifying the locale parameter (e.g. ?locale=es_ES) the string may be returned in the specified language.
  • The Event object now has five new integer fields: attending_count, declined_count, maybe_count, noreply_count and invited_count: Each of these returns an integer which represents the number of people who have been invited, not replied, are attending, are not attending or whom may attend.
  • GET /v2.1/?id={url} returns a new URL node: In v2.1, when you query the Graph API with a URL as the ID, we'll return a URL object which enumerates any share info available for that URL, any Open Graph object associated with that URL, or any AppLinks that use the URL.
  • The Page object now has a new screennames edge: this returns a list of the other, non-Facebook accounts associated with the brand or entity represented by a Facebook Page.


  • The FQL and REST APIs are no longer available in v2.1: Previously announced with v2.0, apps must migrate to versioned Graph API calls starting with v2.1.
  • The '/insights' edge on the Application object is no longer available in this version: This has been replaced by the new '/app_insights' edge.

90-Day Deprecations

The following deprecations will take place on November 5, 2014 - 90 days after the launch of v2.1.

  • The Recommendations Bar social plugin has been deprecated: On Wednesday November 5th 2014, the Recommendations Bar will no longer render on any website. If you're using this plugin, we recommend you remove it from your site before this date.
  • The /insights edge on the Application object will be removed in both v1.0 and v2.0: The insights API is classified as an Extended API and is subject to change within the life of a version. Developers should instead move to call /v2.1/{app_id}/app_insights before this deprecation takes effect.
  • The 'liked' property will no longer be returned in the 'signed_request' object for Page Tab apps created after today. From November 5, 2014 onwards, the 'liked' property will always return 'true' regardless of whether or not the person has liked the page.


  1. API responses are now always JSON objects, rather than booleans, integers or strings: Many API calls before v2.1 returned plain text 'true' or a raw number like '378293782' as the response. With v2.1, those calls will now return valid JSON, such as: { “success”: true }
  2. The dialogs/oauth endpoint no longer support the 'return_session' and 'session_version' parameters for legacy authentication methods.
  3. /v2.1/me/permissions no longer contains the 'installed' permission: 'installed' was a pseudo-permission that was used to check if someone had your app installed. Instead of looking for 'installed' in the response, you should call the endpoint and, if it returns data, consider this indication that the user has installed the app.
  4. GET /?id={your_url} for Open Graph object and Shares has been replaced by new URL node: Previously, when you queried the Graph API with a URL as the ID, we returned information related to shares of that URL. If the URL was also an Open Graph object, you would have to specify 'type=og' in your request. Version 2.1 introduces a new URL node which combines and replaces this functionality.
  5. /v2.1/{post-id} will now return all photos attached to the post: In previous versions of the API only the first photo was returned with a post. This removes the need to use FQL to get all a post's photos.
  6. 'uri' can no longer be requested from picture fields: Apps previously requesting uri should instead use url.

Changes to Platform Policies

  • Games which include mandatory or optional in-app charges must now disclose this in their app's description, either on Facebook or other platforms it supports. This is to give people a clear indication that your game may charge people during gameplay.
  • You must not incentivize people to use social plugins or to like a Page. This includes offering rewards, or gating apps or app content based on whether or not a person has liked a Page. It remains acceptable to incentivize people to login to your app, checkin at a place or enter a promotion on your app's Page. To ensure quality connections and help businesses reach the people who matter to them, we want people to like Pages because they want to connect and hear from the business, not because of artificial incentives. We believe this update will benefit people and advertisers alike.

These policy changes will come into effect on November 5, 2014 - 90 days after the launch of v2.1. They apply to all apps across all API versions.