Ads API Version 3



Ads API Version 3

Today we are releasing version 3 of the Ads API.

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. See our Versions page for details on our versioning strategy.

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 @ricegum trending amongst this audience.

The Audience Intelligence endpoints will provide the following functionality:

  • Given an input audience, retrieve the top relevant hashtags, @handles and 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 a media_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 the card_uri or id. Previously, this was not possible.

Other changes

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



  • The maximum targeting criteria batch size is now 500.
  • The card_uri and preview_url response attributes are now mutually exclusive. When a card has a card_uri the preview_url will be null. When a card does not have a card_uri, only the preview_url will be returned.
    • We are continuing to migrate all cards to use card_uri:
      • All cards created as of 2018-01-29 will have a card_uri.
      • By version 4, all existing cards will have a card_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).



The existing reference documentation has been updated to reflect the v3 changes.

We are excited to see how partners innovate as we continue to deliver new products and features. Please reach out to us with any questions or feedback.

Twitter Ads API Team

V2 notes

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.

Version 3.0 not working
Card_uri found null in scheduled_tweets response
The "card_uri" property of "scheduled_tweets" API shows the "null" value
Corresponding line item (and higher level) data not retrieved where a promoted tweet is found
GET statuses/lookup changed the entity>urls



Media Forward Polls are now part of v3. See announcement for details.


We’ve published a Media Library guide with details on functionality and usage.


We have updated our Python and Ruby SDKs to version 3. For details, see the Python release notes and the Ruby release notes.

Update to get access to v3 endpoints and to complete your v3 migration. As a reminder, v2 of the Ads API will be shut off on 2018-08-01.


In an effort to facilitate the migration to our POST batch/accounts/:account_id/targeting_criteria endpoint, we are listing the differences between the non-batch and batch endpoints in terms of how targeting types are specified. The batch endpoint exposes the operator_type parameter. This adds flexibility and reduces the number of targeting_type enums.

( :arrow_left: scroll :arrow_right: )

non-batch batch
targeting_type=EXCLUDE_APP_LIST "targeting_type":"APP_LIST","operator_type":"NE"
targeting_type=NEGATIVE_BEHAVIOR "targeting_type":"BEHAVIOR","operator_type":"NE"
targeting_type=NEGATIVE_EXACT_KEYWORD "targeting_type":"EXACT_KEYWORD","operator_type":"NE"
targeting_type=NEGATIVE_PHRASE_KEYWORD "targeting_type":"PHRASE_KEYWORD","operator_type":"NE"
targeting_type=NEGATIVE_UNORDERED_KEYWORD "targeting_type":"UNORDERED_KEYWORD","operator_type":"NE"
targeting_type=NETWORK_ACTIVATION_DURATION_GTE "targeting_type":"NETWORK_ACTIVATION_DURATION","operator_type":"GTE"
targeting_type=NETWORK_ACTIVATION_DURATION_LT "targeting_type":"NETWORK_ACTIVATION_DURATION","operator_type":"LT"
targeting_type=TAILORED_AUDIENCE&tailored_audience_type=EXCLUDED_* "targeting_type":"TAILORED_AUDIENCE","operator_type":"NE"
targeting_type=TAILORED_AUDIENCE&tailored_audience_expansion=true "targeting_type":"TAILORED_AUDIENCE_EXPANDED"

( :arrow_left: scroll :arrow_right: )

With the batch endpoint, it’s no longer necessary to specify the tailored_audience_type (e.g., CRM, EXCLUDED_CRM, etc.). That is determined based on the audience itself.

For additional details see:


We wanted to provide some additional details on our non-batch targeting criteria response structure. In version 3, we started work to make our targeting criteria responses consistent, biasing toward the existing batch response. Our v3 changes affected the responses for the following endpoints:

All targeting criteria requests now return the operator_type response attribute. This means that any operator, such as negation (e.g., the “negative” part of a NEGATIVE_BEHAVIOR targeting criterion), is displayed in the operator_type field. As a result, this changes the targeting_type values you will see. This only affects the following targeting types:

( :arrow_left: scroll :arrow_right: )

TC create (non-batch) request (targeting_type) TC create (non-batch) response read response
EXCLUDE_APP_LIST "targeting_type":"APP_LIST","operator_type":"NE" "targeting_type":"CUSTOM_APP_LIST","operator_type":"NE"
NEGATIVE_BEHAVIOR "targeting_type":"BEHAVIOR","operator_type":"NE" same as on create
NEGATIVE_EXACT_KEYWORD "targeting_type":"EXACT_KEYWORD","operator_type":"NE" same as on create
NEGATIVE_PHRASE_KEYWORD "targeting_type":"PHRASE_KEYWORD","operator_type":"NE" same as on create
NEGATIVE_UNORDERED_KEYWORD "targeting_type":"UNORDERED_KEYWORD","operator_type":"NE" same as on create

( :arrow_left: scroll :arrow_right: )

Below are v2 and v3 example responses to show the difference in more detail.

# v2
  "name":"Partner audience targeting",

# v3
  "name":"Partner audience targeting",

Twitter Ads API team

Negative targeting types coming in as positive targeting types with operator type NE
Negative targeting types coming in as positive targeting types with operator type NE
Batch targeting call not working for EXCLUDE_APP_LIST