Instagram Marketing API Update: Legacy Fields Deprecation Now Schedule for September

This is an important update regarding the deprecation timeline for legacy Instagram fields within the Marketing API. Marketing API v21.0 is set to be deprecated on September 9, 2025, which means after September 9, 2025, there will be no Marketing API version available that supports these legacy fields. This date is earlier than the previously announced deprecation date of January 21, 2026.

Beginning with Marketing API v22.0, the ‘instagram_actor_id’ , ‘instagram_story_id’ and ‘effective_instagram_story_id’ fields will be replaced by ‘instagram_user_id’, ‘source_instagram_media_id’, and ‘effective_instagram_media_id’.

At Meta, we have been working to consolidate API endpoints and improve coherence across our Instagram Graph API and Marketing API. The acceleration of deprecating these legacy fields is part of our ongoing commitment to enhance the developer experience by providing a more streamlined, privacy-safe, and efficient platform for building integrations.

What This Means for Developers

We urge all developers utilizing Instagram legacy fields in their Marketing API integrations to migrate to use the new fields before September 9, 2025. This proactive migration will ensure uninterrupted functionality of your apps and services after this date. 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.0.

Impacted API Calls

Some example API calls that need be updated include the following:

• GET /<adset_id>?fields=instagram_actor_id
• GET /<adgroup_id>?fields=creative{instagram_actor_id}
• GET /<adcreative_id>?fields=instagram_actor_id,instagram_story_id,effective_instagram_story_id
• GET /<adcreative_id>?fields=object_story_spec{instagram_actor_id}
• GET /generatepreviews
• GET /act_<adaccount_id>/generatepreviews
• POST /act_<adaccount_id>/adcreatives
• POST /act_<adaccount_id>/ads
• POST /act_<adaccount_id>/asyncadrequestsets
• POST /<adgroup_id>
• POST /<adgroup_id>/copies

For more comprehensive information and detailed implementation guidelines, please refer to our developer documentation.