Introducing Graph API v25.0 and Marketing API v25.0
By Manjari Jain
Here are the highlights of the new GAPI/MAPI changes below for V25. Please visit our changelog for a complete list of changes and details.
General Updates
Graph API: Introducing Page Viewer Metric
By the end of June 2026, we plan to introduce Page Viewer Metric in the Graph API. Viewers metric is intended to replace the legacy reach metric and provide a consistent cross-platform measurement (Facebook and Instagram) of how many people saw a piece of content. Developers should begin planning migration to viewers to ensure continued access to audience insights.
What’s changing?
Viewer metrics will be available in page insights & story insights
Post/Page Insights
- GET {page-id}/insights/page_total_media_view_unique*
- GET {post-id}/insights/post_total_media_view_unique*
Story Insights
- New metric will be added
- GET {stories-id}/insights/metric
- PAGE_STORY_TOTAL_MEDIA_VIEW_UNIQUE
Above Graph APIs will be available after V25 launch, We recommend developers check the Graph API Changelog for the most up-to-date information.
Webhooks mTLS Certificate Update
Starting March 31, 2026, Meta will begin signing Webhooks mTLS certificates using a different Certificate Authority (CA) owned by Meta.
What does this mean for developers?
If your servers are configured to require and verify the Webhooks mTLS certificate, you must trust the new Meta CA. Failure to update your trust store by the deadline will result in TLS handshake failures, and your servers will stop receiving all webhooks events.
Action required: Update Your Trust Store
To ensure uninterrupted receipt of Webhooks, you must
- Download the Meta root CA certificate: Go to Get started with webhooks and download the file named meta-outbound-api-ca-2025-12.pem.
The root CA will sign the leaf certificate which will be presented in Webhooks requests. - Add it to your trust store: Add this certificate to the trust store of any servers receiving Webhooks.
- Maintain the current certificate: You should add the new certificate to your trust store while the current one is still active.
Important: Do not wait until the deadline. You should add the new certificate to your trust store immediately to ensure a seamless transition on March 31.
Deadline: Before March 31, 2026.
Why this change
The current Webhooks mTLS certificate is signed by the DigiCert root CA. Because DigiCert is deprecating the use of the Client Authentication EKU, the certificate cannot be renewed with this root CA expires on April 15, 2026.
Consequently the new Webhooks mTLS certificate will be signed by a Meta internal root CA. It will maintain the same common name (client.webhooks.fbclientcerts.com) as the current certificate.
The public documentation about Webhooks mTLS has been updated with a notification regarding this change. Full technical details in the documentation will be permanently updated in April 2026 once the transition is complete.
Deprecations & Breaking Changes
Enhanced Error Messaging for Ads Insights Async API
We are continuously working to improve the developer experience with our APIs. To provide greater transparency and enable developers to build more resilient applications, we are enhancing the error reporting for the Ads Insights Async API GET {AD_REPORT_RUN_ID} endpoint.
Beginning with the next Graph API version V25.0 which will be released on Feb 18, 2026, developers will have access to detailed error information when an asynchronous report fails, enabling easier diagnosis of failures, and improving the efficiency of their API integrations. For any developers who currently have access to the error_code field, the type will be changed from uint to int.
What's Changing?
We are introducing the following new default fields to the response of the Ads Insights Async API GET {AD_REPORT_RUN_ID} endpoint for all applications:
- error_code: The error code. Note: Field will be changed from
uinttointfor any developers who currently have access to it - error_message: A message corresponding to the
error_code. - error_subcode: The specific subcode for the error.
- error_user_title: A user-friendly title for the error subcode.
- error_user_msg: A user-friendly message detailing the error subcode.
These fields will be populated when a report run fails. We encourage you to review your API integration to ensure compatibility with the new default fields in the response.
This update is planned to be released with the next Graph API version. We recommend developers check the Graph API Changelog for the most up-to-date information. Developer documentation has also been updated to reflect these changes.
Graph API: Metadata Query Parameter Deprecated
Starting with Graph API v25, we are deprecating the metadata=1 query parameter. This parameter was previously used to return metadata about a node's fields and connections within API responses. This feature has low usage and is being deprecated to simplify the platform. After deprecation, the metadata parameter will be ignored in API requests.
Developers who currently rely on metadata=1 should transition to using our official API documentation to discover available fields and connections for each node type.
What's changing?
Change | Timeline |
| v25 (February 2026) |
| May 2026 |
Before (v24 and earlier):
Adding ?metadata=1 to a Graph API request returned additional metadata about the node, including available fields and connections.
After (v25+):
The metadata=1 parameter will be ignored. Requests including this parameter will continue to return standard responses without metadata. No failures or breaking changes will occur - your requests will not error or break if they include metadata=1; the parameter will simply have no effect.
Graph API: Page Reach/Impressions Metrics Deprecation
In June 2026, we plan to deprecate the Post/Page Reach, Video Impressions, and Story Impressions metrics in Graph API. These legacy metrics are no longer surfaced in our Insights tools, but they remained available via APIs until now.
To align our products and APIs on a single, consistent metrics framework—and to improve overall system reliability—we are retiring these legacy metrics. After deprecation, developers should migrate to the new Media Views and Media Viewers metrics, which replace the legacy impression, reach, and video viewers concepts.
What is changing?
The following metrics will be deprecated in June 2026 for all API versions. We recommend developers check the Graph API Changelog for the most up-to-date information:
- GET {page-id}/insights/page_impressions_unique*
- GET {page-id}/insights/page_impressions_paid_unique*
- GET {page-id}/insights/page_impressions_viral_unique*
- GET {page-id}/insights/page_impressions_nonviral_unique*
- GET {page-id}/insights/page_posts_impressions*
- GET {page-id}/insights/page_posts_impressions_unique*
- GET {page-id}/insights/page_posts_impressions_paid*
- GET {page-id}/insights/page_posts_impressions_paid_unique*
- GET {page-id}/insights/page_posts_impressions_organic_unique*
- GET {page-id}/insights/page_posts_served_impressions_organic_unique*
- GET {page-id}/insights/page_posts_impressions_viral*
- GET {page-id}/insights/page_posts_impressions_viral_unique*
- GET {page-id}/insights/page_posts_impressions_nonviral*
- GET {page-id}/insights/page_posts_impressions_nonviral_unique*
- GET {post-id}/insights/post_impressions_unique*
- GET {post-id}/insights/post_impressions_paid_unique*
- GET {post-id}/insights/post_impressions_fan_unique*
- GET {post-id}/insights/post_impressions_organic_unique*
- GET {post-id}/insights/post_impressions_viral_unique*
- GET {post-id}/insights/post_impressions_nonviral_unique*
- GET {post-id}/insights/post_impressions_nonviral_unique*
- GET {video-id}/video_insights/post_impressions_unique
- GET {video-id}/video_insights/total_video_impressions
- GET {video-id}/video_insights/total_video_impressions_unique
- GET {video-id}/video_insights/total_video_impressions_paid_unique
- GET {video-id}/video_insights/total_video_impressions_paid
- GET {video-id}/video_insights/total_video_impressions_organic_unique
- GET {video-id}/video_insights/total_video_impressions_organic
- GET {video-id}/video_insights/total_video_impressions_viral_unique
- GET {video-id}/video_insights/total_video_impressions_viral
- GET {video-id}/video_insights/total_video_impressions_fan_unique
- GET {video-id}/video_insights/total_video_impressions_fan
- GET {video-id}/video_insights/total_video_impressions_fan_paid_unique
- GET {video-id}/video_insights/total_video_impressions_fan_paid
- Two metrics will be replaced
- GET {stories-id}/insights/metric
- PAGE_STORY_IMPRESSIONS_BY_STORY_ID
- PAGE_STORY_IMPRESSIONS_BY_STORY_ID_UNIQUE
We recommend using the following metrics instead:
- GET {page-id}/insights/page_total_media_view_unique
- GET {post-id}/insights/post_total_media_view_unique
Specifically for breakdowns between paid and organic reach, we recommend using the following metrics, which provide substantially similar insights:
- GET {page-id}/insights/page_media_view
- GET {post-id}/insights/post_media_view
Graph API: 3-second Viewers Metrics Deprecation
In June 2026, we plan to deprecate 3-second viewers metrics. These legacy metrics are no longer surfaced in our Insights tools, but they remained available via Graph API until now.
To align our products and APIs on a single, consistent metrics framework—and to improve overall system reliability—we are retiring these legacy metrics. After deprecation, developers should migrate to the new Media Views and Media Viewers metrics, which replace the legacy impression, reach, and video viewers concepts.
What is changing?
The following metrics will be deprecated in June 2026 for all API versions. We recommend developers check the Graph API Changelog for the most up-to-date information:
- GET {page-id}/insights/page_video_views_unique
- GET {post-id}/insights/post_video_views_organic_unique
- GET {post-id}/insights/post_video_views_paid_unique
- GET {post-id}/insights/post_video_views_unique
- GET {video-id}/video_insights/total_video_views_organic_unique
- GET {video-id}/video_insights/total_video_views_paid_unique
- GET {video-id}/video_insights/total_video_views_unique
We recommend using the following metrics instead:
- GET {page-id}/insights/page_total_media_view_unique
- GET {post-id}/insights/post_total_media_view_unique
Specifically for breakdowns between paid and organic 3-second viewers, we recommend using the following metrics, which provide substantially similar insights:
- GET {page-id}/insights/page_media_view
- GET {post-id}/insights/post_media_view
Marketing API: ASC and AAC deprecation
Automation Unification drives App, Sales and Leads campaigns to default to the optimal, automation-first Advantage+ setup and allows advertisers and partners simplified access to Meta’s latest and most performant automation products. We are executing a phased deprecation of the legacy APIs and migration to the new Automation Unification, Advantage+ setup for Marketing API developers.
From V25.0 (18th February 2026) ASC and AAC campaigns can no longer be created or updated using the Marketing API, this will extend to all MAPI versions after 90 days (by May 19th 2026).
In V26.0 (estimated September 2026) all remaining ASC and AAC campaigns will be paused.
ASC or AAC campaigns utilizing Existing Customer Budget Caps (ECBC) will remain editable until V26.0, this feature is not available with Advantage+ campaigns. Developers with an ECBC campaign should take action using one of the below methods to replicate ECBC campaigns before V26.0:
- Manual Duplication: Open an existing ASC/AAC campaign with ECBC in Ads Manager, you will be prompted to ‘Duplicate Campaign’. This 1-click step will create a new campaign that replicates the setup of the existing one.
- Replicate ECBC campaigns using the API, use the guidance provided in developer documentation to replicate the campaigns using the API, here.
- Request bulk migration at the ad account level, for managed partners we are able to provide a one time action to replicate all ECBC campaigns on an agreed date. Please reach out to your Meta POC and provide the Account IDs and preferred date to migrate.
Note: Note all ECBC campaign duplications will result in a new campaign ID.
This change affects the following endpoints:
- POST /{campaign-id}
- POST /{campaign-id}/copies
Please review the updated developer docs and FAQs to see all details of this change.
Link to developer documentation
Link to help article on feature
API Version Deprecations:
As part of Facebook’s versioning schedule for Graph API and Marketing API, please note the upcoming deprecations:
Graph API
- May 21, 2026: Graph API v.19 will be deprecated and removed from the platform.
- September 24, 2026: Graph API v.20 will be deprecated and removed from the platform.
To avoid disruption to business, we recommend migrating all calls to the latest API version that launched today.
Get our newsletter
Sign up for monthly updates from Meta for Developers.