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

VersionPathIntroduction DateDeprecated DateEnd of Life Date
12.0/12/October 27, 2022TBDTBD
11.0/11/March 31, 2022TBDTBD
10.0/10/August 31, 2021March 31, 2022October 27, 2022
9.0/9/March 2, 2021August 31, 2021March 31, 2022
8.0/8/September 8, 2020March 2, 2021August 31, 2021
7.0/7/March 3, 2020September 1, 2020March 2, 2021
6.0/6/August 28, 2019March 3, 2020September 1, 2020
5.0/5/February 28, 2019August 28, 2019March 3, 2020
4.0/4/August 28, 2018February 28, 2019August 28, 2019
3.0/3/February 1, 2018August 28, 2018February 28, 2019
2.0/2/July 10, 2017February 1, 2018August 1, 2018
1.0/1/March 31, 2016July 7, 2017January 10, 2018
0.0/0/February 21, 2013N/AOctober 31, 2016

​
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.

Note: As of this release, Version 7 (v7) 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.

​
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.

​
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, the targeting type in the response included an _IN_SEC suffix. Having a reference to seconds was confusing as Network Activation Duration is always represented in months. This fix makes the representation consistent and reduces confusion.

| v4 | v5 | | :--- | :--- | :--- | | NETWORK_ACTIVATION_DURATION_IN_SEC | NETWORK_ACTIVATION_DURATION | |

Total counts and cursors

In v5, with_total_count and cursor are exclusive. Specifying both in a request will return the EXCLUSIVE_PARAMETERS error code. Prior to v5, with_total_count was ignored when cursorwas specified. This change makes the relationship explicit..

​
Removed

Three fields are being removed from Ads API responses: preview_url, account_id, and parent_ids. The engineering level of effort for these three is minimal.

  • In v4, it was announced that the preview_url response parameter for cards was always null. The final step in this migration is to remove preview_url from all cards responses.
  • The account_id response attribute is being removed for the following resources given that the ads account ID is already present in the URL as well as in request.params. (It is intentional to exclude funding instruments from this list as parent IDs should be present in response objects, where possible, and account IDs are parent entities to funding instruments.)
    • Account media
    • App event providers
    • App event tags
    • Campaigns
    • Cards
    • Line items
    • Promotable users
    • Targeting criteria
  • For GET accounts/:account_id/targeting_criteria requests, we no longer return the parent_ids field as it was always an empty array.

Non-media app cards

In v5, non-media app cards are no longer supported. Previously, the ability to create or edit non-media app cards was removed. Now, the remaining endpoints for this resource are being deprecated.

  • Note: This does not affect image and video app download cards.

Account media creates

The POST accounts/:account_id/account_media endpoint is no longer available in v5. Other endpoints for this resource are not affected. The reason for this change is that, when adding media to the Media Library, there are cases when those assets automatically get added as Account Media entities and trying to add an already-existing asset to the Account Media resource results in an error. This happens in the following cases.

  • AMPLIFY_VIDEO assets added to the Media Library are automatically added as Account Media asset with the PREROLL creative type.
  • Images with specific dimensions added to the Media Library are automatically added as Account Media assets. The creative type (e.g., INTERSTITIAL) depends on the image dimensions. (For dimensions, see our Enumerations page.)

​
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.

v3v4
NARROWDEFINED
BALANCEDEXPANDED

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.

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.x.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.x.com "/3/accounts/18ce54d4x5t/videos"

  • v4 media library endpoint for videos: twurl -H ads-api.x.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 X 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

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.

​
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.

Breaking Changes/Deprecations

  • total_count is now an optional response attribute. It will only be available if with_total_count is set to true

  • paused and draft_only fields on line_items and campaigns request and response objects are replaced by a single entity_status parameter

  • The status parameter has been renamed to text on the POST accounts/:account_id/tweet and GET accounts/:account_id/tweet/preview endpoints

  • The GET targeting_criteria/locations endpoint’s location_type enums are now plural. COUNTRY is now COUNTRIES, REGION is now REGIONS, and so on. The one exception is that, in v2, CITY is now METROS, to correctly reflect the fact that the location type refers to Designated Marker Areas (DMAs) or “metros”.

  • display_properties on the PUT accounts/:account_id/promoted_tweets endpoints. This value will also no longer be returned as part of the response

  • As a result of the previous point, it is no longer possible to update (PUT) promoted_tweets entities

  • The line_item_id parameter on the GET accounts/:account_id/promoted_tweets endpoint has been removed

  • It will no longer be possible to create 5:2 Website Cards  on the v2 endpoints

  • data_type response attribute is no longer returned

New Features

  1. Cards v2
  2. Draft campaigns/line item creations and activations
  3. Scheduled Tweets
  4. Async Job Summaries

Cards v2

  • The card_uri request parameter should be used in favor of appending the preview_url to the Tweet text when associating a card with a Tweet
  • If the card_uri param is not returned in the response (during the card creation step) then use the preview_url
  • All new card formats will be natively availabe on the API, taking advantage of the card_uri parameter.

New Card Formats:

Draft Campaigns

Draft Camapiangs have been available to view via the GET accounts/:account_id/camapaigns endpoint. With v2, it is now possible to create/activate draft campaigns via the API.

Draft CampaignDraft Line Item
funding_instrument_idcampaign_id
nameobjective
start_timeproduct_type
placements

Notes

  • Draft line items or campaigns may only be converted from a entity_status of DRAFT to PAUSED or ACTIVE
  • In order to activate an entire campaign (with multiple line items), each line item under the campaign, as well as the campaign itself must be set to an entity_status of ACTIVE.
  • In order to change the entity_status of any campaign or line item, use the corresponding PUT endpoint.

Scheduled Tweets

​
v1

Version 1 of the Ads API launched on March 31, 2016 and will reach its end of life on January 10, 2018.

Changes in version 1:

  • Versioning support
  • CUSTOM objective is no longer supported
  • Batch endpoints are now generally available
  • Reach estimate changes:
  • To provide better reach estimation, the endpoint is now budget aware. The following parameters are now required:
    • [new] campaign_daily_budget_amount_local_micro
    • currency
    • bid
    • objective
  • The response object has changed, and now returns ranges for response values.
  • infinite_count has been renamed infinite_bid_count to avoid confusion on its purpose
  • In addition to count and infinite_bid_count, these new data points will now be returned:
    • impressions
    • engagements
    • estimated_daily_spend_local_micro
  • Data type change for tailored audiences
  • The data_type for Tailored Audiences has been changed from tailored_audiences to tailored_audience in all of our resposnes.
  • Shared Tailored Audiences are now available as an API-only beta. Shared tailored audiences allow for a single audience to be used across multiple ads accounts. Use the POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions (and related) endpoint to manage permissions of a tailored audience you would like to share across ads accounts.
  • Significant improvements in how you collect performance analytics for advertiser accounts:
  • To align with our best practices, we will now only allow data to be pulled for up to 7 days of data for the synchronous stats endpoints.
  • To simplify pulling metrics, we have replaced the metrics parameter with a new metric_groups parameter. Developers simply must request which groups of metrics they would like returned for a given request.
    • Any request for metrics that are not appropriate for a given entity will be excluded from the response and represented as null values. These metrics will not count against your analytics cost limit.
  • The response has been significantly simplified, and will now align more closely with how metrics are exposed in our UI.
    • Previously we exposed a separate metric for each placement location (Promoted Tweets in Search, Promoted Tweets in Timelines, Promoted Tweets in Profiles & Tweet Details, X Audience Platform). We will now return a standardized set of metrics for each (instead of promoted_tweet_timeline_impressions, promoted_tweet_search_impressions, promoted_tweets_profile_impressions, promoted_tweets_tpn_impressions), these will now be exposed when requested in one of the following categories as a single metric, impressions (this applies to all metrics):
    • ALL_ON_TWITTER
    • PUBLISHER_NETWORK
    • When you make a request you’ll get a single impressions metric to make matching values in our UI simplier.
    • You must make two queries to get both ALL_ON_TWITTER and PUBLISHER_NETWORK data, as these cannot be combined.
  • Asynchronous stats endpoints are now available, based on feedback from our developers!
    • A new set of endpoints to request stats asynchronously, for data you don’t need immediately or for historic data pulls.
    • Queue a stats job using a new single endpoint. We’ll pull the data you have requested as resources allow.
    • You can query a job status endpoint to determine if the data is available.
    • Once the data is available, we’ll provide a pick-up ID for you to download the JSON response, which will mirror the response from the synchronous endpoint.
    • Query up to 90 days of data on up to 20 entities in a single job.
  • Take a look at our analytics v1 migration guide, which includes mapping of v0 metrics to v1 metrics
  • Sandbox improvements * You may now create multiple test ads accounts in the Sandbox environment. * You may now create multiple funding instruments for a test ads account in the Sandbox environment only. This allows you to test on all of our funding instrument types. Previously only a CREDIT_CARD funding source was available to test with. * Want to test a beta feature? You can now toggle features on/off for an account in the Sandbox environment to accommodate your testing needs.

​
v0

Version 0 of the Ads API was officially launched on February 21, 2013 and was supported until October 31, 2016.

All version 0 analytics endpoints are deprecated and will no longer exist after October 31, 2016. These endpoints have been replaced with 3 analytics endpoints in version 1.

The reach estimation endpoint has new behavior in version 1.