Version 22.0

Insights APIs

Applies to all versions.

Insights APIs for both media and user objects are now available for apps that have implemented Instagram API with Instagram Login.

Insights metrics

Introducing the following metrics field for media and user insights:

• views

Metric Deprecations

Applies to v22.0+. Will apply to all versions April 21, 2025.

• clips_replays_count on media insights
• ig_reels_aggregated_all_plays_count on media insights
• impressions on media and user insights
• plays on media insights

Note: API requests with the impressions metric will continue to return data for media created on or before July 1, 2024 for v21.0 and older. API requests made after April 21, 2025 for media created on or after July 2, 2024 will return an error.

Ad Creatives

Applies to v22.0+. Will apply to all versions January 20, 2026.

Field Deprecations

The instagram_actor_id field for the following endpoints is:

• POST /{ad-account-id}/adcreatives
• GET /adcreative
• GET /adcreative/object_story_spec

Please migrate your API calls to use the new [instagram_user_id` field.

The effective_instagram_story_id field has been deprecated for the GET /adcreative endpoint. Use the effective_instagram_media_id field instead.

The instagram_story_id field has been deprecated for the GET /adcreative endpoint. Use the source_instagram_media_id field instead.

Advantage+ Creative

Standard Enhancements

Applies to v22.0+.

Opting ads in to and previewing ads using the STANDARD_ENHANCEMENTS bundle is no longer supported.

The following endpoints are affected:

• POST /{ad-account-id}/adcreatives
• POST /{ad-account-id}/ads
• GET /{ad-id}/previews
• GET /{ad-account-id}/generatepreviews

Asset Feed Spec

Segment Asset Customization

Applies to v22.0+.

Segment Asset Customization is no longer supported.

Audiences

Detailed Targeting - Employer Exclusions

Applies to all versions.

An employer exclusion can now be created at the ad account level, which will be applied to all active campaigns.

The following endpoints are affected:

• POST /{ad-account-id}/account_controls
• GET /{ad-account-id}/account_controls

Detailed Targeting - Exclusions

Applies to v22.0+. Will apply to all versions April 21, 2025.

• When creating or updating an ad set, an error message will be shown when adding any new detailed targeting exclusions that are not within audience control exclusions at the account level.
• When duplicating an ad set, detailed targeting exclusions (except audience control exclusions at the account level) will be removed in the new campaign.
• When trying to get a delivery estimate, only employer exclusions will be allowed for detailed targeting.

As a result of this change, custom audiences will be deprecated within the exclusions field. You can still continue using custom audience exclusions by using the excluded_custom_audiences field instead. For more details see Advanced Targeting: Custom Audiences.

The following endpoints are affected:

• POST /{ad-account-id}/adsets
• POST /{adset-id}
• POST /{adset-id}/copies
• GET /{ad-account-id}/delivery_estimate

Reach People Interested in Selected Cities and Regions

Applies to v22.0+.

Expands location targeting beyond an ad campaign's target cities or regions to deliver ads to people who have shown interest in a location.

The following endpoints are affected:

• POST /{ad-account-id}/adsets
• POST /{adset-id}
• GET /{adset-id}
• GET /{ad-account-id}/delivery_estimate

Commerce Platform

Promotions API – field deprecation

Applies to v22.0+.

The promotions field has been deprecated and replaced by the promotion_details field. Please discontinue using the promotions field, as it does not contain complete information. Please migrate your API calls to the new promotion_details field.

The following endpoint is affected:

• GET /{commerce-order-id}/promotion_details

Instagram Endpoints

Applies to v22.0+. Will apply to all versions April 21, 2025.

The Instagram endpoints supported by the Marketing API have been deprecated.

The following endpoints are affected:

• DELETE /{instagram-comment-id}
• GET /{instagram-carousel-id}
• GET /{instagram-carousel-id}/comments
• GET /{instagram-comment-id}
• GET /{instagram-comment-id}/replies
• GET /{instagram-media-id}
• GET /{instagram-media-id}/comments
• GET /{instagram-user-id}
• GET /{instagram-user-id}/agencies
• GET /{instagram-user-id}/ar_effects
• GET /{instagram-user-id}/authorized_adaccounts
• GET /{instagram-user-id}/upcoming_events
• POST /{instagram-user-id}/authorized_adaccounts
• POST /{instagram-carousel-id}/comments
• POST /{instagram-comment-id}
• POST /{instagram-comment-id}/replies
• POST /{instagram-media-id}
• POST /{instagram-user-id}/upcoming_events

Please migrate your API calls to use the following Instagram Platform endpoints:

• IG User
• IG Media
• IG Media Children
• IG Comment
• IG Comment Replies

Special Ad Categories

Certain customer list custom audiences will become ineligible for usage in ad sets of housing, employment, and financial products and services, including credit, campaigns beginning March 2025. Learn more about the update here and whether the restrictions apply to you.

Ad Sets for Special Ad Category Campaigns

Applies to v22.0+. Will apply to all versions March 2025.

Starting with v22.0, you will be unable to create or update ad sets if their targeting options contain one or more ineligible customer list custom audiences. You will need to either certify if eligible or remove any such audiences to successfully create or update the ad set. Starting early April 2025, existing campaigns/ad sets using customer list custom audiences which do not follow the requirements may be paused. If this happens, you will see errors in Ads Manager and the Marketing API with instructions.

The is_sac_cfca_terms_certified field will be added to the ad set API. You will be required to use this field to certify that any customer list custom audiences being used in an ad set of a housing, employment, and financial products and services, including credit, campaign comply with Meta’s CLCA certification.

This change affects the following endpoints when creating or updating ad sets:

• POST /{ad-account-id}/adsets
• POST /{ad-set-id}

Custom Audiences

Applies to all versions.

Starting on January 6, 2025, you can use the new is_eligible_for_sac_campaigns field to identify whether a custom audience can be used in ad sets of Special Ad Category campaigns. You must provide the intended special_ad_categories and special_ad_category_countries of the Special Ad Category campaign using the audience, as well as the ad_account_id which will use the audience to create or edit the ad set.

This change affects the following endpoints:

• GET /{custom-audience-id}

See Special Ad Categories for more information about these changes.