Recent Changes

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

May 20, 2015

• New attribute and parameter bid_type on line items to support a new pricing mechanism, target bidding, now available in beta to developers, with automatically_select_bid to be fully deprecated by late-July. Affects all endpoints that return line item objects, and in particular:
  • POST accounts/:account_id/line_items
  • PUT accounts/:account_id/line_items/:line_item_id

May 6, 2015

• Ads API support now available (in closed beta) for the Brand Twitter Publisher Network (TPN):
• New attributes advertiser_domain and categories added to POST /0/accounts/:account_id/line_items
• Added GET /0/line_item/placements
• Added GET /0/iab_categories
• Added GET /0/accounts/:account_id/app_lists
• Added GET /0/accounts/:account_id/app_lists/:app_list_id
• Added POST /0/accounts/:account_id/app_lists
• Updated Metrics and Segmentation
• Updated POST accounts/:account_id/targeting_criteria

April 28, 2015

• Added Country Targeting and Display Requirements.

April 22, 2015

• All analytics endpoints now utilize cost-based rate limiting.
• The placement_type parameter has been deprecated on the POST accounts/:account_id/line_items endpoint and is replaced by product_type and placements.

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

• The bid_unit parameter has been added to POST accounts/:account_id/line_items.

April 5, 2015

• Installed App Store Category targeting is now available in the API.

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

• Media (images) for all card endpoints must now utilize our media/upload endpoint. We no longer accept uploads via the image or image_data parameters, for both POST and PUT methods, on our website, lead generation, app download and image app download cards.
• The X-Request-Cost header is now being returned for all analytics endpoints.

March 4, 2015

• The optimization parameter has been added to the POST accounts/:account_id/line_items and PUT accounts/:account_id/line_items/:line_item_id endpoints.

February 10, 2015

• We have added an upcoming changes page to the Ads API docs.

February 4, 2015

• Age targeting is now available in the API.

January 29, 2015

• A new parameter, primary_web_event_tag, has been added to POST accounts/:account_id/line_items and will now be returned on both GET accounts/:account_id/line_items and GET accounts/:account_id/line_items/:line_item_id.

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

• We have updated our targeting docs to support network operators and new device activation.

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

• Currency has been removed from account objects, and spend metrics have been removed from analytics endpoints that span funding instruments, as previously announced.
• We have added support for Tweet delegation in the Ads API. See the POST accounts/:account_id/tweet and GET accounts/:account_id/authenticated_user_access docs for details on how to use this new feature.
• We have launched Behaviors in beta. Currently the only feature available as part of Behaviors are partner audiences, which enable advertisers to reach users on Twitter based on their shopping behaviors and other off-Twitter profiles. See the GET targeting_criteria/behaviors, GET targeting_criteria/behavior_taxonomies, POST accounts/:account_id/targeting_criteria, PUT accounts/:account_id/targeting_criteria endpoints for details.
• For a given MAP metric (such as mobile_conversion_installs), we will provide a breakdown metric (i.e. mobile_conversion_installs_breakdown) that includes post-view conversions, post-engagement conversions, and assisted conversions. See our metrics page for all available breakdowns available.
• The PUT /0/accounts/:account_id/line_items/:line_item_id endpoint now accepts null to unset total_budget_amount_local_micro on ad groups/line items.
• We have published our analytics best practices.

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

• We have added support for dynamic values in our web pixels, including tw_sale_amount and tw_order_quantity. See the POST account/:account_id/web_event_tags and GET accounts/:account_id/web_event_tags/:id endpoint docs. For more details, see conversion tracking for websites.
• We have added support for a new segmentation type CONVERSION_TAGS to provide analytics on a web_event_tag basis. When used, this new segmentation type will only return web conversion metrics for analytics. Two new metrics have been added in along with other conversion metrics we expose today: conversion_sale_amount and conversion_order_quantity. Please refer to Metrics and Segmentation in Analytics for more information.

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

• goal_settings has been officially deprecated
• GET accounts/:account_id/targeting_criteria/tailored_audiences was deprecated as it has been replaced with the GET accounts/:account_id/tailored_audiences endpoint.
• Automatically select tweet campaigns now will only serve the promoted tweets automatically selected as of October 6th moving forward, as the feature is disabled.

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

• In the first stage of our deprecation, automatically_select_tweets is now optional on our POST accounts/:account_id/line_items and PUT accounts/:account_id/line_items/:line_item_id endpoints.

August 28, 2014

• We’ve updated our docs for tailored audience uploads via POST ton/ta_data and PUT ton/data to use OAuth 1.0A instead of OAuth 2.0.

August 27, 2014

• We’ve updated our Tailored Audiences docs to include response samples and we have hashing code samples included at Tailored Audience File Data.

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

• We have updated our doc for POST accounts/:account_id/cards/lead_gen to include custom_destination_url and custom_destination_text.

August 6, 2014

• Objective-based Campaigns support has been enabled for all partners in the API. The following endpoints have been updated to support objective:
• GET accounts/:account_id/line_items
• GET accounts/:account_id/line_items/:line_item_id
• POST accounts/:account_id/line_items
• PUT accounts/:account_id/line_items/:line_item_id

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

• As announced in May, the match_relevant_popular_queries parameter has been deprecated for line_items and will no longer be returned in our responses as of now.
• We have added a new card stats endpoint for website cards: GET stats/accounts/:account_id/cards/website/:card_id
• We have added a new card stats endpoint for app download cards: GET stats/accounts/:account_id/cards/app_download/:card_id
• We have added a new card stats endpoint for image app download cards: GET stats/accounts/:account_id/cards/image_app_download/:card_id

June 17, 2014

• Image App Card endpoints have been released for Mobile App Promotion
• GET accounts/:account_id/cards/image_app_download
• GET accounts/:account_id/cards/image_app_download/:card_id
• POST accounts/:account_id/cards/image_app_download
• PUT accounts/:account_id/cards/image_app_download/:card_id
• DELETE accounts/:account_id/cards/image_app_download/:card_id

June 11, 2014

• Mobile App Promotion has been announced for partners.
• GET accounts/:account_id/cards/app_download
• GET accounts/:account_id/cards/app_download/:card_id
• POST accounts/:account_id/cards/app_download
• PUT accounts/:account_id/cards/app_download/:card_id
• DELETE accounts/:account_id/cards/app_download/:card_id

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

• We have added an approval_status field to the GET accounts, GET accounts/:account_id, GET accounts/:account_id/promoted_tweets and GET accounts/:account_id/promoted_accounts endpoints. Possible values in this new field are ACCEPTED, UNDER_REVIEW or REJECTED. See Content Approval Status for more context.

May 20, 2014

• The GET targeting_criteria/tv_shows endpoint will now return a max of 50 results per call.

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

• The match_relevant_popular_queries parameter has been deprecated for line_items. This affects POST accounts/:account_id/line_items and PUT accounts/:account_id/line_items/:line_item_id. The attribute will be removed from our line_items responses at the end of June 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

• The total_budget_amount_local_micro parameter is now optional on campaign creation when using the POST accounts/:account_id/campaigns endpoint.
• Two additional types were added for POST accounts/:account_id/web_event_tags and PUT accounts/:account_id/web_event_tags/:id endpoints: SIGN_UP and CUSTOM.

April 15, 2014

• The GET accounts/:account_id/scoped_timeline endpoint has been moved from /1/ to /0/. We will support traffic to /1/ until the end of June.
• The GET accounts/:account_id/reach_estimate endpoint has been moved from /1/ to /0/. We will support traffic to /1/ until the end of June.

March 26, 2014

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

March 18, 2014

• Updated location_type as optional in GET targeting_criteria/locations

March 14, 2014

• Added web_event_tag endpoints:
• GET accounts/:account_id/web_event_tags
• GET accounts/:account_id/web_event_tags/:id
• POST accounts/:account_id/web_event_tags
• PUT accounts/:account_id/web_event_tags/:id
• DELETE accounts/:account_id/web_event_tags/:id

January 19, 2014

• Added lead_gen card endpoints:
• GET accounts/:account_id/cards/lead_gen
• GET accounts/:account_id/cards/lead_gen/:card_id
• POST accounts/:account_id/cards/lead_gen
• DELETE accounts/:account_id/cards/lead_gen/:card_id
• GET stats/accounts/:account_id/cards/lead_gen/:card_id

January 6, 2014

• Added sub-segmentation types for LOCATION and PLATFORM to the following endpoints:
• GET stats/accounts/:account_id
• GET stats/accounts/:account_id/campaigns/:id
• GET stats/accounts/:account_id/line_items/:id
• GET stats/accounts/:account_id/promoted_accounts/:id
• GET stats/accounts/:account_id/promoted_tweets/:id
• GET stats/accounts/:account_id/funding_instruments/:id
• GET stats/accounts/:account_id/funding_instruments
• GET stats/accounts/:account_id/campaigns
• GET stats/accounts/:account_id/line_items
• GET stats/accounts/:account_id/promoted_accounts
• GET stats/accounts/:account_id/promoted_tweets

December 11, 2013

• Added broad_keywords to relevant targeting related pages.
• Updated Targeting, POST accounts/:account_id/targeting_criteria, PUT accounts/:account_id/targeting_criteria.

December 5, 2013

• Added clarification to the process of promoting a Tweet from a promotable_user (no need to RT anymore)
• Updated GET accounts/:account_id/promotable_users.

November 25, 2013

• Broad Keyword Match Updates
• Updated Targeting.
• Updated POST accounts/:account_id/targeting_criteria.
• Updated PUT accounts/:account_id/targeting_criteria.

November 14, 2013

• Released enhanced analytics endpoints. All docs updated.

November 13, 2013

• Release of Enhanced Mobile Targeting.
• Added GET targeting_criteria/platform_versions.
• Added GET targeting_criteria/devices.
• Updated PUT accounts/:account_id/targeting_criteria.
• Updated POST accounts/:account_id/targeting_criteria.
• Updated Targeting.

September 24, 2013

• Added GET accounts/:account_id/targeting_suggestions.
• Updated Analytics, added information on Segmentation Reporting.
• Updated GET stats/accounts/:account_id/campaigns/:id, added segmentation_type parameter documentation.
• Updated GET stats/accounts/:account_id/line_items/:id, added segmentation_type parameter documentation.
• Updated GET stats/accounts/:account_id/promoted_accounts/:id, added segmentation_type parameter documentation.
• Updated GET stats/accounts/:account_id/promoted_tweets/:id, added segmentation_type parameter documentation.

July 29, 2013

• Updated POST accounts/:account_id/line_items, added missing documentation for match_relevant_popular_queries parameter.
• Updated PUT accounts/:account_id/line_items/:line_item_id, added missing documentation for match_relevant_popular_queries parameter.

July 23, 2013

• Created GET accounts/:account_id/brands_tv, GET accounts/:account_id/brands_tv documentation.
• Updated POST accounts/:account_id/targeting_criteria, updated for TV Targeting feature.
• Updated PUT accounts/:account_id/targeting_criteria, updated for TV Targeting feature.

July 01, 2013

• Updated Advertising API, added active campaign limits.
• Updated POST accounts/:account_id/campaigns, added active campaign limits.
• Updated POST accounts/:account_id/line_items, added include_sentiment documentation.
• Updated PUT accounts/:account_id/line_items/:line_item_id, added include_sentiment documentation.
• Updated Targeting, added negative keyword targeting types to list of valid targeting for PTwT.

June 27, 2013

• Updated PUT accounts/:account_id/campaigns/:campaign_id, minor change, removed funding_instrument argument, it is silently ignored on PUT.

June 14, 2013

• Updated PUT accounts/:account_id/campaigns/:campaign_id, describing how to nullify the end_time value.
• Updated Analytics, describing the true complexity of a stats call using granularity=TOTAL (spoiler warning: it is the same as granularity=DAY).

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

• Updated GET accounts/:account_id/reach_estimate, we renamed 2 parameters to be more consistent with the language in POST accounts/:account_id/targeting_criteria.

May 03, 2013

• Published GET stats/accounts/:account_id/promoted_accounts/:id, documentation specific to retrieving Promoted Accounts stats.

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

• Update to PUT accounts/:account_id/targeting_criteria. New error message. Targeting deleted or invalid users will return an error block with an INVALID_TWITTER_USER_ID message.

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

• The line_item_id is now optional for GET accounts/:account_id/promoted_tweets and GET accounts/:account_id/promoted_accounts. Omitting the line_item_id will return all associated objects for all campaigns of a the specific advertiser.

Mar 6, 2013

• Added some clarification for acceptable bid_amount_local_micro values for line items (non zero, positive integers). See POST accounts/:account_id/line_items and PUT accounts/:account_id/line_items/:line_item_id.

Mar 1, 2013

• New endpoint: GET accounts/:account_id/promotable_users. Returns the collection of promotable_users associated with an account, now that accounts can have multiple users.

Feb 28, 2013

• Updates to GET stats/accounts/:account_id, GET stats/accounts/:account_id/campaigns/:id and GET stats/accounts/:account_id/line_items/:id to include the new estimated_charge_local_micro metric. The previously documented estimated_spend_local_micro was an error, the real metric is estimated_charge_local_micro.

Feb 25, 2013

• Additional parameter for PUT accounts/:account_id/line_items/:line_item_id: match_relevant_popular_queries, Makes your line_item eligible to be shown for trending terms that are relevant to the keywords that you’ve targeted.

January 8, 2013

• Exact keyword matching, along with negative keyword matching for all keyword types is now functional. See POST accounts/:account_id/targeting_criteria and PUT accounts/:account_id/targeting_criteria for usage. See this article for more information on our keyword targeting features.
• The implementation behind gender targeting in PUT accounts/:account_id/targeting_criteria has changed. Targeting can only be applied to “0” (no gender targeting), “1” (male), or “2” (female). Targeting multiple genders in a single line item is not possible.

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

• Removed promoted_by_user_id parameter from POST accounts/:account_id/line_items.
• Clarified that automatically_select_tweets can only be set to true for for placement_type=PROMOTED_TWEETS_IN_TIMELINES.
• The targeting criteria query methods are now ready for more rigorous use. You’ll find the usage semantics have changed slightly. Use these methods to retrieve targeting criteria:
• GET targeting_criteria/interests
• GET targeting_criteria/locations
• GET targeting_criteria/platforms

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.