Home
Blog
Making it easier to build integrations across the Instagram API and Marketing API

January 21, 2025

Making it easier to build integrations across the Instagram API and Marketing API

By Shravya Garlapati

Today, we’re announcing several changes to the Instagram Graph API and the Marketing API to make it easier for developers to build solutions for businesses.

Replacing Instagram User, Instagram Media, Instagram Carousel, and Instagram Comment endpoints with IG User, IG Media, and IG Comment endpoints

With these changes, we are deprecating the `Instagram User, `Instagram Media`, `Instagram Carousel`, and `Instagram Comment` objects in Graph API v22 in favor of the existing `IG User`, `IG Media` which includes carousels, and `IG Comment` objects. We’ve also added functionality to these newer objects to provide parity for most use cases, with details below on what’s not supported.

Developers will have until January 21, 2026 to migrate Marketing API endpoints and until April 21, 2025 to update Graph API endpoints. See below for a list of which endpoints are changing and what timeline applies. If you are automatically updating your Graph API versions in your API calls, we recommend you review these changes as they apply immediately for developers using Graph API v22.

When you migrate, these fields will no longer be available:

  • For `Instagram Media`, the filter_name, location, location_name, latitude, longitude, fields are removed. We will also remove the permalink and caption fields of carousel child media.
  • For `Instagram Comment`, the mentioned_instagram_users, comment_type, mentioned_instagram_users, and comment_type fields are removed.
  • For `Instagram User`, the is_private field is removed. Additionally, many `IG user` fields will be hidden moving forward for accessing page backed instagram accounts.

When you migrate, there are a number of changes, outlined below.

Comparing `Instagram User` to `IG User`:

  • follow_count is now follows_count
  • followed_by_count is now followers_count
  • profile_pic is now profile_picture_url

New fields and edges on `IG User`:

  • has_profile_picture
  • is_published
  • /authorized_adaccounts
  • /agencies
  • /upcoming_events

Comparing `Instagram Media` and `Instagram Carousel` to `IG Media`:

  • The taken_at field corresponds to the timestamp field in IG Media
  • The content_type corresponds to the media_type field in IG Media. An enum string value is returned instead of int (e.g. 0 → IMAGE, 1 → VIDEO, 4 → BROADCAST, 8 → CAROUSEL_ALBUM).
  • The `caption_text` corresponds to the caption field in IG Media. The caption of a carousel child object is not available. The “@” symbol is removed for users mentioned in the caption unless the app user is also able to perform admin-equivalent tasks on the Facebook Page connected to the Instagram account used to create the caption. When there’s no caption, we’ll return an empty string, instead of null.
  • The `display_url` for images and `video_url` for videos have been simplified into a single field, `media_url`. The `display_url` field for video media corresponds to `thumbnail_url`.
  • The `owner_instagram_user` field corresponds to the `owner` field, which now returns an IG User instead of Instagram User.
  • Fields that return aggregated values don't include ads-driven data. For example, comments_count returns the number of comments on a photo, but not comments on ads that contain that photo.

Comparing `Instagram Comments` to `IG Comment`:

  • The instagram_user field corresponds to the `user` field, which now returns an IG User instead of Instagram User.

We’ve also introduced the `ig_user_id`, `ig_media_id`, and `ig_comment_id` fields to legacy objects on Graph API v21 and prior as well as `legacy_instagram_user_id`, `legacy_instagram_media_id`, and `legacy_instagram_comment_id` to the new objects to make it easier to begin using the corresponding endpoints. These ID fields will be available until April 21, 2025.

For marketing APIs with `instagram_actor_id` and `instagram_story_id` fields/parameters, those will be replaced with `instagram_user_id` and `instagram_media_id` using IG user and IG media’s ID correspondingly. Any edge returning Instagram User previously will return IG User moving forward as well.

The following endpoints are part of the Marketing API and will no longer support legacy objects beginning on January 21, 2026:

  • GET /generatepreviews
  • GET /act_<adaccount_id>/generatepreviews
  • GET /<adcampaign_id>
  • GET /<adcreative_id>
  • GET /<asyncadrequest_set_id>/requests
  • GET /<asyncadrequest_id>
  • POST /act_<adaccount_id>/adcreatives
  • POST /act_<adaccount_id>/ads
  • POST /act_<adaccount_id>/asyncadrequestsets
  • POST /<adgroup_id

The following endpoints are part of the Graph API and will no longer support legacy objects on April 21, 2025:

  • GET /{instagram-user-id}
  • GET /{instagram-user-id}/agencies
  • GET /{instagram-user-id}/upcoming_events
  • GET /{instagram-user-id}/authorized_adaccounts
  • POST /{instagram-user-id}/upcoming_events
  • POST /{instagram-user-id}/authorized_adaccounts
  • GET /{instagram-media-id}
  • GET /{instagram-media-id}/comments
  • GET /{instagram-carousel-id}
  • GET /{instagram-carousel-id}/comments
  • GET /{instagram-comment-id}
  • GET /{instagram-comment-id}/replies
  • POST /{instagram-media-id}/comments
  • POST /{instagram-carousel-id}/comments
  • POST /{instagram-comment-id}/replies
  • POST /{instagram-comment-id}
  • DELETE /{instagram-comment-id}
  • GET /<page_id>/instagram_accounts
  • GET /<page_id>/page_backed_instagram_accounts
  • GET /<business_id>/owned_instagram_accounts
  • GET /<business_id>/instagram_accounts
  • GET /<business_asset_group_id>/contained_instagram_accounts
  • GET /<fb_business_user_id>/assigned_instagram_accounts
  • GET /<fb_user_id>/assigned_instagram_accounts
  • GET /<fb_system_user_id>/assigned_instagram_accounts
  • GET /act_[ad account id]/instagram_accounts
  • GET /act_[ad account id]/connected_instagram_accounts_with_iabp
  • POST /<page_id>/page_backed_instagram_accounts
  • DELETE /<business_id>/instagram_accounts

Providing more clarity on views in Insights API

In August 2024, Instagram introduced Views as the primary consumption metric so businesses and creators can better understand how their content is performing. Whether their content's format is a reel, live, photo, carousel, or stories, partners and businesses are able to use the views metric to measure the performance of their content.

To improve metric quality as well as continue aligning the functionality of Instagram API with that of the Instagram app, we are introducing the `views` metric on all API versions for both media and user insights. For media insights, Feed, Story and Reels objects will return views. For user insights, the API will support the `views` metric with multi-dimensional breakdowns for follower type and media product type for `total_value` metric type.

In addition, the following metrics will be deprecated starting in v22:

  • plays (media insights): Number of times the reels start to play after an impression is already counted.
  • clips_replays_count (media insights): The number of times your reel starts to play again after an initial play of your reel. This is defined as replays of 1ms or more in the same reel session.
  • ig_reels_aggregated_all_plays_count (media insights): The number of times your reel starts to play or replay after an impression is already counted.
  • impressions (media & user insights): Total number of times the Instagram Media object has been seen.

The media insights `impressions` metric will only be deprecated for media created on or after July 2, 2024. For media created before this date, the API will continue to return values as usual across all versions.

More information can be found in our developer documentation for Instagram User Insights and Instagram Media Insights. Please make sure to update your app by April 21, 2025 to avoid issues.


Get our newsletter

Sign up for monthly updates from Meta for Developers.

Sign up