Instagram Platform Updates & Release Notes

Ordered comments for Instagram ad media

Applies to all versions.

Added the /ordered_comments edge (GET //ordered_comments). It returns comments in Instagram display order, and the response can include comments from all of an ad’s Instagram media. The /ordered_comments edge is available for the Instagram API with Facebook Login only.

Captions on stories published through the Content Publishing API

Applies to all versions.

A caption set when creating a story container now appears on the published story as a caption from your app user’s account.

Caption add-ons for polls and comment prompts

Applies to all versions.

The Content Publishing API now supports caption add-ons. A caption add-on is either a poll, which offers two to four options for end users to vote on, or a comment prompt, which invites end users to reply in the comments. Add-ons are supported on feed posts and reels. Stories are not supported. Only available in Instagram API with Facebook Login.

To attach an add-on, set one of the new parameters when creating a media container:

• poll_attachment — A JSON object containing the options for the poll
• is_poll_duration_extended — a poll runs for 3 days by default. Set this to true to leave the poll open indefinitely
• is_comment_prompt_used — set to true to attach a comment prompt

A media can carry at most one caption add-on, so poll_attachment and is_comment_prompt_used cannot be used together on the same post.

Two new endpoints for reading the caption add-ons. Both return null when the media has no add-on of that type, and both reject story media.

Endpoints

• POST //media with the poll_attachment, is_poll_duration_extended, or is_comment_prompt_used parameter
• GET //poll_attachment — returns the poll’s options and the share of votes each option received
• GET //prompt_response — returns a paginated list of responses to the comment prompt

New Content Publishing errors

Applies to all versions.

New errors returning in the content publishing flow to help you debug the API request failure:

• The Facebook account linked to the Instagram account is restricted and cannot publish video
• The account or the merchant is not eligible for product tagging
• The caption is too long. The error now reports the length of the caption and the maximum allowed
• The caption contains too many hashtags, or the request tags too many users

Requests to graph.instagram.com that include a parameter supported only in Instagram API with Facebook Login, such as the branded content or caption add-on parameters, now return a 400 response naming the unsupported parameter. These parameters were previously ignored.

Non-blocking issues in the content publish response

Applies to all versions.

A media publish can succeed while part of the request is dropped, most often when the caption fails an integrity check.

The publish response now includes a config_issue field when this happens. The publish still succeeds and the field is omitted when there is nothing to report. Possible values:

• CAPTION_NOT_ATTACHED — the media published without its caption
• USER_TAGGING_FAILURE — the media published without its user tags

Endpoint

• POST //media_publish

More actionable Instagram Login authorization errors

Applies to all versions.

The Instagram Login authorization flow’s 400 Session Invalid error now returns more detailed underlying reason, including when the account is checkpointed or unconfirmed.

Sync your Instagram app name in the App Dashboard

Applies to all versions.

The Instagram app settings page in the App Dashboard now has a Sync app name button that sets your Instagram app’s name from your connected Facebook app, with an - IG suffix.

Creator Marketplace Messaging API

Applies to all versions.

Introducing the Instagram Creator Marketplace Messaging API, which lets a brand using your app send paid partnership messages to creators through the Partnership folder on Instagram. The API requires the new instagram_creator_marketplace_messaging permission and a Page access token for a Page connected to a brand that has onboarded to Instagram’s creator marketplace.

Creators must be onboarded to the creator marketplace, have 250,000 or fewer followers, and allow message access to receive partnership messages. Only available in Instagram API with Facebook Login.

Endpoints

• GET //creator_marketplace_creators?fields=messaging_id,is_paid_partnership_messages_enabled
• POST //messages?folder=partnership
• GET //conversations?platform=instagram&folder=partnership
• GET //messages

Sandboxed test accounts

You can now test the Creator Marketplace Messaging API end to end before App Review using sandboxed Instagram test accounts. Add two public Instagram accounts as Instagram Testers on the same app — one business account for the brand, linked to a Facebook Page, and one creator account for the creator — and accept both invitations. When both accounts are accepted testers on the same app with standard access, Creator Marketplace onboarding and eligibility checks are bypassed, Discovery returns a real messaging_id for the creator test account, and you can create a paid-partnership thread and send a message to that creator.

Facebook creators on the Creator Marketplace API

Applies to all versions.

The Creator Marketplace API now returns creators who publish on Facebook. Use the new platform parameter to include them, or page_name to look a creator up by the name of their Facebook Page. Creators carry a new platforms array plus page_id and page_name, and creator insights, media, and media insights accept a .platform() modifier that resolves each metric per platform. Two new account metrics are available on both platforms: total_views and account_interactions.

Endpoints

• GET //creator_marketplace_creators

New Creator Marketplace Discovery API filters and fields

Applies to all versions.

The Creator Marketplace API Discovery API accepts six new filter parameters: creator_language, has_portfolio, has_public_contact_email, exclude_messaged_creators, verified_account, and featured_in_paid_ads. Each result carries three new fields: category, is_brand_following_creator, and is_creator_following_brand.

creator_states and major_audience_states are no longer limited to the United States. State and region codes now resolve against the country you supply, so each requires exactly one paired country value.

recommendation_type accepts a new interested_in_collaboration value.

Endpoints

• GET //creator_marketplace_creators

Higher rate limit for the Creator Marketplace Discovery API

Applies to all versions.

The account-level rate limit is now 5,000 calls per user per hour, up from 1,000.

Download and copyright protections on media_url

Applies to all versions.

The media_url field on the IG Media endpoint is now omitted from responses in either of these cases:

• The video contains copyrighted or licensed audio, including audio added from the Instagram audio library, or it has been flagged for a copyright violation. This applies to all video media, including reels, video posts, and video stories, and applies even when the app user owns the media.
• The reel owner has turned off downloads for the reel, through either the account-level or per-reel Allow people to download your reels setting. This applies to reels only, and only on the endpoints listed below that read other users’ media. The setting is evaluated against the reel’s owner, so it can apply to a reel you co-authored. Reading your own media through GET //media or GET / is not affected by this condition.

This gives media returned by the Instagram APIs the same download and copyright protections that already apply in the Instagram app. All other fields on the media object, such as id, permalink, caption, and timestamp, are returned as normal. Image media and carousel containers are not affected, though a carousel’s video children can be. Requests still return a 200 response. Treat media_url as an optional field in your app and fall back to permalink or thumbnail_url when it is absent.

This change applies to both graph.facebook.com and graph.instagram.com.

Endpoints affected by both the download setting and copyright checks

• GET /?fields=business_discovery{media}
• GET //tags
• GET //mentioned_media
• GET //mentioned_comment
• GET //top_media
• GET //recent_media
• GET //collaborative_media

Endpoints affected by the copyright check only

• GET /
• GET //children
• GET //media
• GET //stories
• GET //live_media
• GET //collaboration_invites

Nested media reached through field expansion, such as carousel children or the media on a comment, inherit the conditions that apply to the originating request. For example, GET //children is subject to the copyright check alone, but children returned by business_discovery{media{children}} are also subject to the download setting.

AI Info Label

Applies to all versions.

The Content Publishing API now supports self-disclosure of AI-generated content at publish time. Set the new is_ai_generated parameter to true when creating a media container to apply the AI info label. For carousels, set is_ai_generated on the carousel container only. Available in both Instagram API with Facebook Login and Instagram API with Instagram Login. is_ai_generated field is also now available on the IG Media endpoint.

Endpoints

• POST /{ig_user_id}/media with the is_ai_generated parameter
• GET /{ig_media_id}?fields=is_ai_generated

New Story Insights Metrics

Applies to all versions.

Introducing a new link_clicks metric on the IG Media Insights endpoint for Story media, returning the number of taps on links in your story (such as link stickers). Only available in Instagram API with Facebook Login.

Endpoint

• GET /{ig_media_id}/insights?metric=link_clicks

Instagram Audio API

Applies to all versions.

Introducing the Instagram Audio API for apps using Facebook Login. The API lets your app search for and retrieve audio — original sounds from Reels and royalty-free music from Meta’s Sound Collection — and attach it to Reels at creation time.

This release also adds an ads use case for discovering replacement audio for Instagram Reels ads: when a Reel contains copyrighted music, your app can find royalty-free Sound Collection tracks to replace it. To apply a discovered track to a Reels ad, see IG Audio Swap for Instagram Reels Ads.

Endpoints

• GET /ig_audio?audio_type={music|original_sound} — Search or retrieve trending audio
• GET /{ig_audio_id} — Get metadata for a specific audio asset
• GET /ig_audio?product=ADS&purpose=AUDIO_COPYRIGHT_REPLACEMENT&audio_replacement_mode={auto|search|default}&ig_media_id={ig_media_id} — Discover replacement audio for Reels ads

New IG Media Field

Applies to all versions.

A new field is now available on the IG Media endpoint:

• media_audio_type — The type of audio used in the media: MUSIC (licensed music from Meta’s catalog) or ORIGINAL_SOUND (original audio). Returned for video media such as Reels.

Endpoint

• GET /{ig_media_id}?fields=media_audio_type

New Media Engagement Fields

Applies to all versions.

Three new fields are now available on the IG Media endpoint for apps using Facebook Login, giving deeper insight into how content is being distributed:

• reposts_count — Number of times the media has been reposted by other users
• saved_count — Number of times the media has been saved
• shares_count — Number of times the media has been shared

Endpoint

• GET /{ig_media_id}?fields=reposts_count,saved_count,shares_count

Aggregated Metrics

Applies to all versions.

Introducing three new aggregated metrics that provide comprehensive engagement totals across all surfaces, including boosted media and Facebook crossposted content. These values match what users see in the Instagram Insights Dashboard and are available through both the IG Media and Insights endpoints:

• total_like_count / total_likes — Aggregated likes across Instagram, Facebook, and promoted media
• total_comments_count / total_comments — Aggregated comments across all surfaces
• total_views_count / total_views — Aggregated views across all surfaces (video media only)

Endpoints

• GET /{ig_media_id}?fields=total_like_count,total_comments_count,total_views_count
• GET /{ig_media_id}/insights?metric=total_likes,total_comments,total_views

Enhanced Views Metrics

Applies to all versions.

• facebook_views expansion: The facebook_views metric now supports Feed post, Reels, and Story media types, and coverage has expanded to include both crossposted plays and cross-app recommended plays.
• Cross-platform view_count: The view_count field now returns combined Instagram and Facebook views for crossposted video content when looking up another user's public media via the Business Discovery API.

Endpoints

• GET /{ig_media_id}/insights?metric=facebook_views
• GET /{ig_user_id}?fields=business_discovery.username({username}).media{view_count}

Collaborative Media API

Applies to all versions.

Introducing the Collaborative Media API on the IG User. The API lets your app retrieve all media where your app user is an accepted collaborator, making it easier to track and measure performance of collaborative content across partnerships.

Endpoints

• GET //collaborative_media — Fetch all collaborative media for the app user
• GET /?fields=collaborative_media_search.media_id() — Search for a specific collaborative media

Partnership Ads Label

Applies to all versions.

The Content Publishing API now supports adding the "Paid partnership" disclosure label at publish time, eliminating the need to manually add partnership labels after publishing. Two new parameters have been added to the create media endpoint:

• branded_content_sponsor_ids — Tag up to 2 brand partners by their Instagram user ID
• is_paid_partnership — Enable the "Paid partnership" label with or without naming specific brands

Endpoint

• POST //media with branded_content_sponsor_ids and is_paid_partnership parameters

See the updated post-level permissioning guidance for details on brand approval flows.

Like Media and Comments API

Applies to all versions.

Introducing the Like Media and Comments API on the IG User. The API lets your app like and unlike Instagram media and comments on behalf of your app users, enabling engagement workflows such as responding to comments on business posts or engaging with collaborative content.

Endpoints

• POST //likes with media_id={media_id} or comment_id={comment_id} — Like a Feed post, Reel, comment, or reply
• DELETE //likes with media_id={media_id} or comment_id={comment_id} — Unlike a Feed post, Reel, comment, or reply

The new instagram_manage_engagement permission is required. Stories and content from private accounts are not supported.

Creator Marketplace

Applies to all versions.

The Creator Marketplace API now includes several new capabilities for discovering and evaluating creators:

• Rate limit increase: Account-level rate limits for the Discovery API have increased from 240 to 1,000 queries per user per hour, enabling faster, higher-volume creator search.
• Profile picture URL: A new profile_picture_url field is available when querying creator profiles.
• Past partnership ads media: You can now query a creator's historical partnership ads media that the creator owns.
• New filters: Three new filtering options — follower growth (top growth in last 30 days), latest activity (recently posted creators), and device type (iOS/Android audience filtering).

See Creator Marketplace API documentation for more information.

Partnership Ads

Applies to all versions.

• Username filtering on ad permissions: The /{business-account-id}/branded_content_ad_permissions endpoint now supports filtering by creator_username, allowing you to search and retrieve ad permissions for a specific creator. See Account-Level Permissioning for more information.
• Ad code generation: Creators can now generate partnership ad codes through the API, enabling automated workflows for branded content authorization. See Ad Codes for more information.