Versioning

Documentation Index

Fetch the complete documentation index at: https://docs.x.com/llms.txt

Use this file to discover all available pages before exploring further.

---

title: Versions keywords: [“Ads API versions”, “API versioning”, “version history”, “API versions”, “version updates”, “Ads API version”] description: For the most up to date information on historical versions of the X Ads API, please reference the information below. | Version | Path | Introduction Dat…--- For the most up to date information on historical versions of the X Ads API, please reference the information below.

​

Overview

Every month, we make changes and roll out several new features on the X Ads API. These changes are nearly always backwards compatible, however we do tend to have a handful of breaking changes each year. We’ve received feedback from developers on the challenges that our fast cadence of changes in the Ads API has on their development cycles when it comes to implementing new features, handling deprecations and testing changes. We want to improve the developer experience using our Ads platform, which is why we introduced the concept of versioning our endpoints. A few definitions of some of the concepts that we talk about: Version: This refers to the version number found in the URL path of any Ads API request, for example: GET //accounts.  This style of versioning is known as URI versioning. Breaking Changes: Breaking changes are any changes that require developer resources to maintain existing functionality. This includes resources used for investigation into the changes that need to be made, determination of features/endpoints being deprecated and final implementation of all these changes. A list of breaking changes are things like: * Removing a param from the API request/response * Modifying the name for any params or endpoints * Change in the representation of values (preview_url → card_uri) * Change in behavior of endpoints (e.g.,  async vs sync stats) * Adding/changing optional or required params (e.g., making name a required field in the request) Deprecation: Deprecated versions or products will be unsupported and it is recommended that developers cease to use these APIs. Sunset: Once a product or API is sunset, the corresponding set of endpoints will no longer be accessible via the API.

​

Versioning Strategy

The main principles of the strategy are: 1. All breaking changes will be bundled into a new version 2. Deprecations for existing versions whenever a new version is announced is 6 months 3. At any given time, the API will allow requests from two versions simultaneously, however the older of the two will be unsupported 4. In order to provide quicker adoption of new products, these will be released on on ongoing basis (outside of the versioning cadence) 5. All API responses will contain a x-current-api-version which will be set to the current version of the API in addition to an x-api-warn header when calling any deprecated API endpoints. Should there be any fundamental product requirement changes that require an API breaking change (e.g. deprecating multiple age bucket targeting), we will send out a 90-day notice to announce this breaking change, and after at least 90 days after the notice is released, the breaking change will be deployed

​

v9

Today, March 3rd, 2021, Version 9 (v9) of the X Ads API is now available. This release is designed to increase feature parity, simplify campaign creation, and to introduce key updates to our Cards and Mobile App Promotion endpoints. As with our previous versions, there will be a 6 month transition period to migrate to v9. On August 31, 2021, the existing version 8 (v8) of the Ads API will no longer be available. We encourage all developers to migrate to the latest version of the Ads API as soon as possible to avoid any service disruptions. For full details, please see the announcement on the developer forum.

​

v8

Today, September 20th, 2020, we introduce Version 8 of the X Ads API, designed to introduce new Tailored Audiences functionality, increase feature parity with ads.x.com, and improve your developer experience. As with previous versions, there will be a 6 month transition period to migrate to v8. On 2021-03-02 version 7 of the Ads API will no longer be available. We encourage all developers to migrate to the latest version of the API as soon as possible to avoid any service disruptions. For full details, please see the announcement on the developer forum.

​

v7

Today, March 20th, 2020, we introduce Version 7 of the X Ads API, designed to increase feature parity with ads.x.com. As with previous versions, there will be a 6 month transition period to migrate to v7. On 2020-09-01, version 6 of the Ads API will no longer be available. We encourage all developers to migrate to the latest version of the API as soon as possible to avoid any service disruptions. Version 5 of the Ads API has reached its end of life and is no longer available. For full details, please see the announcement on the developer forum.

​

v6

Today, August 28, 2019, X is introducing Ads API v6, with updates that focus on consistency and improving the developer experience. This release includes a new endpoint for retrieving Tweets, stats for Promoted Accounts, the ability to search for entities by name, and information about the current number of processing asynchronous analytics jobs. In addition, we’ve made consistency-focused updates to endpoints that use media and to our targeting criteria endpoints. Finally, we’ve made minor updates to some of our parameter names and response attributes and are deprecating the Scoped Timeline endpoint. For full details, please see the announcement on the developer forum.

​

v5

Today, February 28, 2019, X introduces Ads API v5, with updates that focus on enabling scale and efficiency. This release includes a new endpoint to determine which entities were active in a given timeframe, stats for Media Creatives (i.e., In-stream videos and images on the X Audience Platform), the ability to fetch multiple cards, by card URI, and more flexibility around retrieving targeting criteria and other entities. In addition, we’ve fixed some bugs and made updates to parameter names and response attributes. Finally, non-media app cards and the POST accounts/:account_id/account_media endpoint have been deprecated. As with previous versions, there will be a 6 month transition period to migrate to v5. On 2019-08-28, version 4 of the Ads API will no longer be available. We encourage all partners to migrate to the latest version of the API as soon as possible to avoid any service disruptions. Version 3 of the Ads API has reached its end of life and is no longer available.

​

New

Determining which entities were active The Active Entities endpoint signifies whether analytics metrics for ads entities have changed. Designed to be used in conjunction with the analytics endpoints, Active Entities works by specifying an entity type and a date range—a maximum of 90 days—and returns an array of entity IDs that your platform should request analytics for. IDs other than the ones returned should not be queried in subsequent analytics requests. This endpoint supports the following entity types:CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, and PROMOTED_TWEET. MEDIA_CREATIVE stats The Ads API’s analytics endpoints now provide metrics for Media Creative entities. Media Creatives are how in-stream ads or images on the X Audience Platform are promoted. The X Ads UI shows Media Creative metrics under the “In-stream videos” and “Display creatives” tabs. Both synchronous and asynchronous analytics endpoints now support the MEDIA_CREATIVE entity enum. Fetch multiple cards Improving on the v3 release of the endpoint designed to retrieve a single card by its card URI value, it’s now possible to fetch multiple cards using the GET accounts/:account_id/cards/all endpoint. Now, rather than making a request for each card, you can retrieve up to 200 cards in a single request. Two things to note: 1. The URL path is now accounts/:account_id/cards/all. (The previous path is no longer available.) This is so that we’re consistent with the endpoint designed to retrieve a card by ID. 2. The required request parameter is now named card_uris (plural). Flexibility around retrieving The GET accounts/:account_id/targeting_criteria endpoint now supports multiple line item IDs. The line_item_ids parameter, which accepts up to 200 IDs, is required. Previously, only a single line item was accepted, which made syncing difficult. With this change, it’s now possible to retrieve more targeting in less time. The following endpoints now also support multiple line item IDs, though the line_item_ids parameter is optional for these. * GET accounts/:account_id/line_item_apps * GET accounts/:account_id/media_creatives * GET accounts/:account_id/promoted_accounts * GET accounts/:account_id/preroll_call_to_actions

​

Changed

Retrieving draft campaigns and line items The way that draft campaigns and line items are retrieved has been updated. Now, the with_draft(boolean) parameter, when set to true, returns both draft and non-draft entities. This is consistent with the way deleted entities are retrieved (i.e., using with_deleted). Previously, fetching both draft and non-draft entities required at least two requests. Now, this can be done in a single API call. | v4 | v5 | | :--- | :--- | :--- | | draft_only | with_draft | | Network activation duration targeting The Ads API has resolved a display issue where, after adding Network Activation Duration targeting, th