Recent Changes

Major Ads API changes to endpoints will be maintained on this page.

October 28, 2016

  • It is now possible to view, edit, and delete draft campaigns via the API. Details on our developer forum.

October 17, 2016

October 12, 2016

  • The website conversions objective (WEBSITE_CONVERSIONS) now requires the use of the target_cpa_local_micro parameter. This affects both creating new and updating existing ad groups (line items).

October 10, 2016

  • Sixteen (16) new age targeting buckets are now available
    • AGE_13_TO_24
    • AGE_13_TO_34
    • AGE_13_TO_49
    • AGE_13_TO_54
    • AGE_OVER_13
    • AGE_18_TO_54
    • AGE_OVER_18
    • AGE_21_TO_34
    • AGE_21_TO_49
    • AGE_21_TO_54
    • AGE_25_TO_49
    • AGE_OVER_25
    • AGE_35_TO_49
    • AGE_35_TO_54
    • AGE_OVER_35
    • AGE_OVER_50

August 4, 2016

  • Support for the beta website conversions objective (WEBSITE_CONVERSIONS) has been added to the API. This objective requires the use of a primary_web_event_tag set on the ad group (line item).

July 28, 2016

  • Reach estimation has been expanded to include keyword, wifi only and age targeting.

May 25, 2016

May 13, 2016

  • The Ads API has moved our standard video view definition to the MRC standard view definition and bidding option for video ads on Twitter.
  • The `video_total_views metric </ads/analytics/metrics-and-segmentation-in-analytics>`__ within the VIDEO metric group will report on any views which are at least 50% in-view for 2 seconds, as per the MRC standard (equivalent to the existing video_mrc_views metric). Data for this new metric definition can be retrieved for time ranges starting from 2015-12-01. This MRC view definition is the default VIEW bid_unit for Video View campaigns.
  • The original video view definition of 100% in view for at least 3 seconds remains available as the new `video_3s100pct_views metric </ads/analytics/metrics-and-segmentation-in-analytics>`__ in the VIDEO metrics group. To continue to bid and be charged based on the original view definition, use the newly available `VIEW_3S_100PCT bid_unit </ads/basics/enums>`__.
  • Both the original and the MRC-based view definitions are available through the ads.twitter.com UI.

March 14, 2016

January 29, 2016

December 2, 2015

  • Flexible Audience, a new type of Tailored Audience, is now available in closed beta through the API through the new tailored Audience batch endpoint. Flexible Audiences allows advertisers to target specific sets of users by creating combinations of existing Tailored Audiences and adding filters based on the recency and frequency of engagement events. During this initial closed beta phase, only mobile Tailored Audiences can be used to create Flexible Audiences.
  • Added POST batch/accounts/:account_id/campaigns
  • Updated Tailored Audience Overview

December 1, 2015

November 20, 2015

October 22, 2015

  • When uploading videos to be used in promoted content, the media_category parameter must be set with a value of amplify_video for all INIT command requests to the POST media/upload (chunked) endpoint. Using this new param ensures that the video is correctly pre-processed and prepared for use in promoted content.
  • Pre-processing will now happen asynchronously to ensure better success rates for video uploads and to eventually provide support for larger video size and length limits. A new STATUS command has been added to the Media Upload API and you can call this command after your FINALIZE command request to ensure that your video has completed its pre-processing and transcoding phase. Async is now the only supported video upload workflow for Ads API developers.
  • Updated Promoted Video Overview
  • Updated POST media/upload (chunked)

October 8, 2015

October 5, 2015

September 14, 2015

  • Media Views metrics are now available through our analytics endpoints. Media Views encompass all views (autoplay and click) of embedded media, across videos, Vines, GIFs, and images. These include both billed and earned views.
  • Using these metrics, Media Views and Media View Rate can be derived for campaigns with objectives of TWEET_ENGAGEMENT or CUSTOM
  • The added metrics are:
  • promoted_tweet_timeline_media_views
  • promoted_tweet_profile_media_views
  • promoted_tweet_search_media_views
  • promoted_tweet_tpn_media_views
  • Updated Metrics and Segmentation
  • Updated Derived Metrics

August 31, 2015

August 24, 2015

August 19, 2015

August 6, 2015

August 3, 2015

  • Added Lifetime Value (LTV) metrics to available metrics and segmentation.
  • Please note LTV metrics are available on all analytics endpoints for advertiser accounts running mobile app promotion (MAP) campaigns with MACT setup.
  • The GET accounts/:account_id/reach_estimate endpoint now supports reach estimation for all bid types. To enable this, additional parameters are available on the endpoint. These new optional parameters are objective, and bid_type.

July 27, 2015

July 8, 2015

  • Added documentation for Tweet Engager Retargeting to the Targeting overview.

June 24, 2015

  • Added promoted_tweet_profile_* metrics to analytics endpoints. For all metrics, see metrics and segmentation. These new metrics include data for Promoted Tweets in Profiles ad inventory.

June 8, 2015

  • A new cost-per-install charging option is now available (in closed beta) for advertisers who have set up mobile app conversion tracking (MACT) with Answers by Fabric. Note that while the use of Answers is mandatory, we do not require that Answers replace the advertiser’s current mobile measurement partner. This feature enables campaigns with objective APP_INSTALL to be charged by app-installs instead of app-clicks:
  • Added new charge_by parameter to POST accounts/:account_id/line_items
  • Updated Ads Enumerations
  • Updated Objective-Based Campaigns

June 2, 2015

May 20, 2015

May 6, 2015

April 22, 2015

April 17, 2015

  • Analytics may now be segmented by CONVERSION_TAGS and APP_STORE_CATEGORY.

April 10, 2015

  • An additional 11 call-to-action (CTA) options have been added to our website cards, available on both POST and PUT endpoints. These new CTAs include: ENROLL_NOW, FIND_A_CARD, GET_A_QUOTE, GET_TICKETS, LOCATE_A_DEALER, ORDER_ONLINE, PREORDER_NOW, SCHEDULE_NOW, SIGN_UP_NOW, SUBSCRIBE, and REGISTER_NOW.

April 8, 2015

April 5, 2015

March 31, 2015

  • It is now possible for null values to be returned in analytics time series when the data would not be valid or was not collected at the time represented.

March 23, 2015

  • The X-Cost-Rate-Limit-Limit, X-Cost-Rate-Limit-Remaining and X-Cost-Rate-Limit-Reset headers are now being returned, in addition to X-Request-Cost, for all analytics endpoints.

March 5, 2015

March 4, 2015

February 10, 2015

February 4, 2015

January 29, 2015

January 28, 2015

  • The user_ids param is now required on the scoped_timeline endpoint.
  • We have removed support for the with_deleted parameter for all stats endpoints. All stats queries will now return results as if with_deleted=true has been set.
  • We have deprecated both the suggested_high_cpe_bid_local_micro and the suggested_low_cpe_bid_local_micro attributes returned for line item responses.

January 7, 2015

  • We have fixed a bug that prevented querying for RETWEET_ONLY user timelines from the scoped_timeline endpoint.

December 22, 2014

December 17, 2014

  • We have introduced several changes to TV targeting to make it easier for brands and advertisers to reach specific TV audiences with Promoted Tweets. These changes involve 2 new endpoints, GET targeting_criteria/tv_genres and GET targeting_criteria/tv_channels. We’ve also updated TV show targeting to target audiences only around a show’s airing window using the new parameter TV_SHOW_AIRING_RESTRICTED.
  • We have added the ability to set a call-to-action (CTA) on both our app_download and image_app_download cards.
  • Additional CTA options have been added for our website cards.
  • TV brand targeting (automatic ad detection) for whitelisted advertisers has been deprecated. We will remove tv_brand endpoints in early January.
  • Tweet delegation endpoint, POST accounts/:account_id/tweet, now supports media_ids
  • Our beta video APIs are now available for whitelisted advertisers. For more information about the video upload APIs and information about usage, please see the video API developer documentation.

December 3, 2014

November 14, 2014

  • Broad targeting is now generally avaialble to all advertisers.

November 5, 2014

  • We have introduced a closed beta for tailored audiences from mobile apps. This is a new type, MOBILE, of tailored audience for mobile app marketers which enables marketers to easily create Tailored Audiences from their mobile app conversion tracking events that populate dynamically, minimizing the ongoing effort required to create and manage audiences.

October 29, 2014

October 23, 2014

  • In August we introduced the concept of multiple line items (now known as ad groups) per campaign. An ad group contains targeting parameters and ads, and currently inherits the daily campaign budget, total campaign budget and campaign schedule that is set on the campaign level. We have now enabled ad group budgets, which will allow you to specify smaller test budgets for each ad group, thus providing more flexibility and control to conduct multivariate testing.
  • We have relaxed our targeting validations, allowing broad targeting options (such as location), and no longer requiring advertisers to choose a primary targeting type. We will no longer require a primary targeting type for campaigns (e.g. interests, keywords, followers, tailored audiences, TV) and you can now create campaigns which target broadly with geo, gender, language, and device/platform criteria

October 8, 2014

  • We will now be referring to Line Items as Ad Groups moving forward. This is how we will be referencing these in our UI and our marketing materials and ask that partners implementing multiple-line items to also refer to these as Ad Groups going forward.

October 7, 2014

  • We have stopped returning estimated_charge_local_micro metric that was deprecated late last year. Ensure you are using billed_charge_local_micro.

October 6, 2014

October 1, 2014

  • We have removed the ignored_values parameter from the targeting_suggestions endpoint as this parameter had not been truly implemented.
  • Our Promoted Video Broad Beta has begun, exposing the objective VIDEO_VIEWS.

September 25, 2014

  • We have enabled Sorting for certain attributes of our Ads API collection endpoints. Most endpoints that return a list of objects will now be sortable by created_at, updated_at, deleted, as well as various additional attributes.
  • We have added documentation for the retrieval of statistics on the following: organic activity for Tweets, Promoted Video, and additional mobile conversion metrics.

September 23, 2014

  • We have added an objective filter to the scoped_timeline endpoint so that partners can fetch only the Tweets appropriate for the objective given.
  • We have deprecated automatically_select_tweets from the line items endpoints.

September 3, 2014

August 28, 2014

August 27, 2014

August 19, 2014

  • The WRITE rate limit, across all endpoints, has been increased from 500/15-minutes to 2000/15-minutes. More details in our overview doc here: Advertising API.
  • We’ve added Tailored Audience File Data to cover file formats for tailored audiences.

August 12, 2014

  • We’ve added a new document for all our Metrics and Segmentation in Analytics. As we make changes to our analytics this will be the new central source of truth for Ads metrics via the API.

August 10, 2014

August 6, 2014

August 5, 2014

  • We’ve added the ability to set and receive the CTA for website cards. The docs for the following endpoints have been updated to reflect this.
  • POST accounts/:account_id/cards/website
  • GET accounts/:account_id/cards/website
  • GET accounts/:account_id/cards/website/:card_id
  • DELETE accounts/:account_id/cards/website/:card_id
  • PUT accounts/:account_id/cards/website/:card_id

July 23, 2014

  • We’ve added the endpoints for tailored audience management so that partners can now manage these lists via the API. The endpoints are all linked from Tailored Audiences.
  • A new document that outlines the functionality differences between our API and our UI has been started -Functionality in API vs Twitter UI

July 01, 2014

June 09, 2014

  • We’ve added endpoints to support Website Cards. These include the following:
  • GET accounts/:account_id/cards/website
  • GET accounts/:account_id/cards/website/:card_id
  • POST accounts/:account_id/cards/website
  • PUT accounts/:account_id/cards/website/:card_id
  • DELETE accounts/:account_id/cards/website/:card_id

June 02, 2014

May 20, 2014

May 07, 2014

  • Several endpoints have been updated to support language targeting announced today. Our Targeting overview page has been updated to include this new targeting type.
  • New endpoint: GET targeting_criteria/languages
  • New languages param added to the PUT accounts/:account_id/targeting_criteria endpoint to support language targeting.
  • New languages param added to the GET accounts/:account_id/reach_estimate endpoint to support language targeting.
  • Our Analytics endpoints have been updated to support a new type of segmentation, LANGUAGES.

May 06, 2014

May 01, 2014

  • The GET targeting_criteria/tv_shows endpoint has been updated to restrict audience to the market that is targetable. As a result audience sizes will no longer be over reported and we will report a minimum estimated_users of 1000 to protect user privacy.

April 21, 2014

April 15, 2014

March 26, 2014

  • Announcing Backend Improvements for April 2014 (link removed).

March 18, 2014

December 11, 2013

December 5, 2013

November 25, 2013

November 14, 2013

  • Released enhanced analytics endpoints. All docs updated.

September 24, 2013

July 29, 2013

July 23, 2013

July 01, 2013

June 27, 2013

June 14, 2013

May 29, 2013

  • Published Pagination, an overview of the upcoming pagination support in the Ads API. Currently available in the Sandbox.

May 24, 2013

  • Updated Timezones, far more complete and in-depth examination of timezone usage in the Ads API.

May 16, 2013

May 03, 2013

Apr 17, 2013

  • Published Keyword Targeting in Timelines for the Ads API following the release the feature to all advertisers.
  • Updated the Targeting overview documentation to reflect the targeting in timelines additions.

Apr 15, 2013

  • New feature: Budget Pacing. Control how fast daily budgets are spent with standard delivery (default) or accelerated delivery.
  • Updated rate limits in the Advertising API overview page. Rate limits are currently at 2000/15 mins/endpoint/token for READ and 500/15 mins/token for WRITE.
  • New Targeting overview documentation. Listing all targeting options by placement type and definition of targeting types and keyword types.

Mar 18, 2013

Mar 15, 2013

  • You can now determine the approximate reach of Promoted Tweet in Timelines and Promoted Account campaigns with GET accounts/:account_id/reach_estimate. Be sure to review the complete list of parameters.

Mar 8, 2013

Mar 6, 2013

Mar 1, 2013

Feb 28, 2013

Feb 25, 2013

January 8, 2013

January 2, 2013

  • GET bidding_rules now responds with a collection (rather than a single instance) of bidding rules when using the currency parameter.

December 20, 2012

  • The automatically_select_tweets parameter on POST accounts/:account_id/line_items is now only required with line items with the placement_type set to PROMOTED_TWEETS_IN_TIMELINES. Its value defaults to false.

December 17, 2012

  • Introducing PUT accounts/:account_id/targeting_criteria for bulk targeting on line items with different semantics to the POST method. Functional examples and updates to related docs will be added to the doc this week, but we wanted to get it in your hands ASAP.

December 13, 2012

December 11, 2012

  • GET bidding_rules documents how to retrieve the minimum and maximum bids for a specific or all currencies.
  • You’ll also now find suggested_low_cpe_bid_local_micro and suggested_high_cpe_bid_local_micro fields as part of line item responses.