Versions

For the most up to date information on historical versions of the Twitter Ads API, please reference the information below.

Overview

Every month, we make changes and roll out several new features on the Twitter 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 /{version_number}/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

v4

Version 4 of the Ads API is launching today, August 28, 2018.

This release includes improvements to our Audiences product, including a new API interface powered by a more robust audience processing backend. Version 4 also includes a set of endpoints for managing user, account, and tax settings. In addition, the accounts/:account_id/videos endpoints are being deprecated. This release also includes a few minor parameter and and response name changes.

As with version 3, we are providing a 6 month transition period. On 2019-02-28, version 3 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. See our Versions page for details on our versioning strategy.

New

Audience API

The new Audiences API is built on our new audience processing backend that provides enhanced robustness and reliability. This new endpoint will allow partners to provide multiple user identifier types for a single user, which means that we are able to use additional signals for matching. Reference documentation for the new Audience endpoint can be found here. We plan to continue to release updates and improvements to this product throughout the rest of year.

The following endpoints will no longer be available in v4 due to redundant functionality (they will still work in v3 and will be fully sunset when v3 is no longer available):

• TON Upload:
  • GET accounts/:account_id/tailored_audience_changes
  • GET accounts/:account_id/tailored_audience_changes/:tailored_audience_change_id
  • POST accounts/:account_id/tailored_audience_changes
  • PUT accounts/:accounti_d/tailored_audiences/global_opt_out
• Real Time Audiences:
  • POST tailored_audience_memberships

Finally, the list_type parameter will be removed from the request and response on all Tailored Audiences endpoints in version 4.

Settings Endpoints

We now provide the ability for account administrators to set and update user, account, and tax settings. User settings correspond to the user-specific contact preferences for a given ads account. Using the PUT accounts/:account_id endpoint, advertisers can now update their account name and industry type. Finally, the tax settings endpoints allow advertisers in countries where a value added tax (VAT) is charged to update information such as the company name, address, VAT ID, and whether the account is owned by the advertiser or by an agency advertising on behalf of an advertiser.

Changed

Universal Lookalike Renames

We’re updating the enum values for the lookalike_expansion parameter on the POST accounts/:account_id/line_items and PUT accounts/:accountit/line_items/:line_item_id endpoints.

Using country_code everywhere

As part of a larger effort around consistency on the Ads API, we’re renaming the parameters on the following endpoints from app_country_code to country_code.

• POST accounts/:account_id/cards/image_app_download
• PUT accounts/:account_id/cards/image_app_download/:card_id
• POST accounts/:account_id/cards/video_app_download
• PUT accounts/:account_id/cards/video_app_download/:card_id

This does not impact the behavior or accepted values for these parameters and is purely a naming change.

preview_url always null

As promised in the v3 announcement, all existing cards now have a card_uri. As a result, the preview_url value will always be null.

As a reminder, associate a card with a Tweet using its card_uri value. See the following example request.

$ twurl -X POST -H ads-api.twitter.com "/4/accounts/18ce54d4x5t/tweet?text=Version 4&card_uri=card://958225772740714496"

Removed

Video endpoints

The accounts/:account_id/videos endpoints will no longer be available in v4. This endpoint has been made obsolete by the introduction of the Media Library endpoints. See the following usage comparison.

# v3 videos endpoint
$ twurl -H ads-api.twitter.com "/3/accounts/18ce54d4x5t/videos"

# v4 media library endpoint for videos
$ twurl -H ads-api.twitter.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"

The Media Library endpoints are in full parity with the videos endpoints and also support additional functionality such as the ability to handle images and GIFs. Partners are requested to use the Media Library exclusively for any media management.

as_user_id in Tweet View

The as_user_id parameter available on the GET accounts/:account_id/tweet/preview/:tweet_id endpoint will no longer be accepted. The preview will always be rendered as the Tweet’s author.

v3

Version 3 of the Ads API launched on February 1, 2018. Version 2 of the Ads API will reach its end of life on August 1, 2018.

This release includes our new Audience Intelligence product, access to the Media Library, and improved card workflows. We are also announcing the deprecation of the PUT accounts/:account_id/targeting_criteria endpoint. Finally, version 3 includes a few minor parameter and response changes and a lower batch size limit.

As with version 2, we are giving partners 6 months to transition. On 2018-08-01, v2 of the Ads API will be shut off. We encourage all partners and developers to migrate to v3 as soon as possible.

Audience Intelligence

Audience Intelligence delivers real-time insights into the top hashtags,@handles, and events most relevant to a given Twitter audience. For example, enter Male 18-34 in the US and you’ll see#nintendoswitch,#cardinal, and@ricegumtrending amongst this audience.

The Audience Intelligence endpoints will provide the following functionality:

• Given an input audience, retrieve the top relevant hashtags,@handlesand events.
• Given an input audience, retrieve key demographic information (such as age, gender, and household income).
• Given a keyword, retrieve the Tweet volume time series

Media Library

The Media Library provides the ability to manage images, GIFs, and videos for ads accounts. These media objects can be used in Tweets and to create cards. They can also be reused in multiple creatives, eliminating the need to upload the same asset multiple times.

Objects in the library are identified by amedia_key. Media keys are string values in the following format:13_875943225764098048, for example. In the Ads API, we are moving toward using media keys for all media.

Improved card workflow

All of our cards endpoints now support media keys. This enables objects in the Media Library to be used to create or update cards.

In addition, we’re introducing two new endpoints for retrieving card details. These endpoints can be used to look up cards used in Tweets or Scheduled Tweets, for example, by specifying either thecard_uriorid. Previously, this was not possible.

Other changes

In addition to these new features, we’re including the following changes to version 3.

New

• The GET insights/keywords/search endpoint response now includes a related_keywords attribute with 30 terms related to the input keywords.

Changed

• The maximum targeting criteria batch size is now 500.
• Thecard_uriandpreview_urlresponse attributes are now mutually exclusive. When a card has acard_urithepreview_urlwill benull. When a card does not have acard_uri, only thepreview_urlwill be returned.
  • All cards created as of 2018-01-29 will have acard_uri.
  • By version 4, all existing cards will have acard_uri.
• It is no longer possible to create cards with 5:2 images. While existing 5:2 image-based cards will still work, we encourage partners to switch to using the higher-performing 1.91:1 or 1:1 aspect ratios (where supported)

Removed

• The PUT accounts/:account_id/targeting_criteria endpoint is no longer available. We’ve decided to make this change because the replace behavior with this endpoint caused advertiser confusion and it was not consistent with our other PUT endpoints that update a single resource at a time. Instead, partners should use the POST batch/accounts/:account_id/targeting_criteria endpoint, which provides greater flexibility including the ability to both add and remove targeting in a single request.
• The paused response attribute is no longer returned for funding instruments. Instead, look to the entity_status response attribute to determine whether or not a funding instrument is paused. In addition, because paused and cancelled correspond to the same value, cancelled is no longer returned in the response, either.
• We have removed the card_id parameter from the GET accounts/:account_id/tweet/preview endpoint.
• Because it is not possible to retrieve deleted Scheduled Tweets, the with_deleted parameter is no longer supported.
• The draft_only parameter has been removed from the following endpoints as these entities can never be in a draft state:
  • GET accounts/:account_id/targeting_criteria
  • GET accounts/:account_id/promoted_tweets
  • GET accounts/:account_id/promoted_accounts
  • GET accounts/:account_id/media_creatives
  • GET accounts/:account_id/preroll_call_to_actions

Note

Both Video Website Cards and Scheduled Tweets are now out of beta. See this thread for the changes we’ve made to Scheduled Tweets since launch. This includes the ability to generate HTML previews for Scheduled Tweets.

Deprecated

v2

Version 2 of the Ads API launched on July 10, 2017. Version 1 of the Ads API will reach its end of life on January 10, 2018.