How do Marketing API versions and deprecations work?
Meta releases a new Marketing API version roughly every four months and keeps the previous one working for at least 90 days. After that, calls to the old version may fail or be upgraded to the next available version. Every call must name a version. As checked on 2 Oct 2026, the current version is v26.0.
Every Marketing API request carries a version number, and Meta retires old numbers on a schedule. If your software or a tool you connect still calls an old number once its window closes, some requests keep working and others break. This page follows Meta’s versioning page, updated 24 June 2026, and the changelog, updated 21 May 2026, as checked on 2 Oct 2026.
How are new versions released?
Meta says it releases all breaking changes in a new version, and that several versions can exist at the same time with different functionality. Versions arrive approximately every four months.
When a new version launches, Meta continues to support the previous one for at least 90 days. During that grace period you can call both. Meta’s example: v17.0 was released on 23 May 2023, and v16.0 expired on 6 February 2024.
Which versions are available right now?
The changelog lists the available versions as it stood on 2 Oct 2026:
| Version | Date introduced | Available until |
|---|---|---|
| v26.0 | July 29, 2026 | TBD |
| v25.0 | February 18, 2026 | TBD |
| v24.0 | October 8, 2025 | October 6, 2026 |
The versioning page names v26.0 as the current version. Check the changelog itself for the list on the day you read this.
What happens to calls to a deprecated version?
Meta says a call to an unavailable version may fail or be upgraded to the next available version. Since May 2024 it has applied auto-upgrade to endpoints that are not affected between versions, so those calls are upgraded instead of failing.
Meta’s own example: after v17.0 was deprecated on 14 May 2024, a POST /{adset-id} call on v17.0 would fail, because v18.0 changed that endpoint. A GET /{ad-account-id}/insights call would be upgraded to v18.0.
Meta still encourages you to upgrade before a version is deprecated. You may need to upgrade the affected endpoints yourself, and a newer version may bring features you want.
How do you know a call was auto-upgraded?
Meta adds a response header to any call it auto-upgraded. The header is X-Ad-Api-Version-Warning, and its text says the call was upgraded to a named version because the version you asked for was deprecated. If you want to turn auto-upgrade off, Meta points to the Marketing API Version setting under Marketing API App Product Page, then Settings.
Which versions can your app call?
Meta says an app can call the version that was latest when the app was created, as long as it is not deprecated, plus any newer, undeprecated version. Meta adds that an app created while one version was latest, but not used until a newer version launched, can use only the newer version.
What should you check before a deprecation date?
- Name a version in every request path, in the form
https://graph.facebook.com/v{n}/{request-path}. - Open the Marketing API changelog and find the version you plan to move to.
- Look up the endpoints that version changes, because those calls are not auto-upgraded.
- Check your API responses for the
X-Ad-Api-Version-Warningheader. - Move your calls to a newer version before the deprecated version’s end date.
FAQ
What happens if you leave the version out of a call?
Meta calls this an unversioned call, and says unversioned calls are invalid and fail against Marketing API endpoints. Meta’s example path puts the version at the start, as in v26.0/me/adaccounts. Always start the path with the version you intend to use.
How is Marketing API versioning different from the rest of the Graph API?
Meta says the Marketing API runs on a 90-day deprecation schedule, while the platform API has core and extended APIs with a two-year guarantee for core APIs. Marketing API calls with no working version fail, so the version always has to be set.
Are old versions removed on a fixed date?
Meta gives at least 90 days after a new version launches, but the changelog lists an end date only for v24.0 (October 6, 2026) and TBD for v25.0 and v26.0. Meta also says it may not always release a new version at the end of the previous version’s 90-day grace period. Read the changelog for current dates.
Sources
- Marketing API versioning (Meta, checked 2 Oct 2026)
- Marketing API changelog (Meta, checked 2 Oct 2026)
Drafted with AI and checked claim by claim against the pages linked under Sources. Found a mistake? Tell us via the corrections policy.