Ads API Versions

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

Version Path Introduction Date End of Life Date
2.0 /2/ July 10, 2017  
1.0 /1/ March 31, 2016 January 10, 2018
0.0 /0/ February 21, 2013 October 31, 2016



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 will be made an optional parameter (will be available only if with_total_count is set to true)
  • display_properties on the PUT promoted_tweets endpoint. This value will also no longer be returned as part of the response
  • paused and draft_only fields on the GET/PUT/POST line_items and GET/PUT/POST campaigns endpoint request/response objects, in favor of a single entity_status parameter
  • status field being renamed to text on the POST tweet and GET tweet/preview endpoint
  • 5:2 Image App Download Cards and Website Cards will no longer be available on the v2 endpoints
  • data_type response attribute is no longer returned
  • 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”.

New Features

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

Cards v2

  • The card_uri param should be used in favor of the preview_url when associating a Tweet with a card
  • 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.

Draft Campaigns

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

  • The entity_status parameter value on the POST line_items and POST campaigns endpoints can be set to DRAFT in order create any new draft campaigns or line items.
  • The set of required parameters for a newly created draft:
Draft Campaign Draft Line Item
funding_instrument_id campaign_id
name objective
start_time product_type
  • 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



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 /1/accounts/:account_id/tailored_audiences/: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, Twitter 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):
    • 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.



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.