Migration Guide; v0 => v1

We recommend you start moving away from analytics v0 endpoints to the newly introduced analytics v1 endpoints as soon as possible. As per our Version 1 Announcement, v0 will be deprecated on June 30, 2016.

Consolidation of analytics endpoints

In version 0 of the Ads API, a separate analytics endpoint existed for each entity type, from funding instruments to promoted tweets to organic tweets. With version 1 of the API, we’ve consolidated these into just two endpoints - one for synchronous stats queries, and another for asynchronous stats queries. These two endpoints can be used to fetch stats for all entity types, specified using the entity and entity_ids parameters. The synchronous endpoint will return smaller batches of data ideal for real-time campaign optimizations. The asynchronous endpoint is intended for larger queries of complex data, ideal for generating reporting or historical backfills.

For more details on these two endpoints and the differences in each, see the Analytics Overview

Rate Limiting

With the introduction of separate synchronous and asynchronous analytics endpoints, we are deprecating cost-based rate limiting in favor of a straightforward query-based rate limiting model similar to our non-analytics endpoints for both v1 analytics endpoints. The asynchronous analytics endpoint will have a per-advertiser limit on the total number of concurrent asynchronous stats queries. For more details on the rate limits for each endpoint, see the Rate Limiting section of the Analytics Overview.

Moving from metrics to metric_groups

The metrics parameter has been deprecated in favor of metric_groups, groupings of related metrics such as video metrics or engagement metrics. This simplifies analytics queries by elimating the need to explicitly query each specific metric. In addition, the metrics will provide an pre-aggregated count across the requested placement, removing the need for aggregation across placements previously required in version 0. A complete list of available metric_groups and their contained metrics is available on our Metrics and Segmentation page. Do note that version 1 provides additional metrics not previously available in version 0, and a select number of metrics previously available in version 0 will no longer be available in version 1.

Simplifying responses using placement

Using the newly introduced placement parameter, we are now able to return a pre-aggregated metrics for all placements across Twitter or on the Twitter Audience Platform. This elimates the need for developers to aggregate metrics across placements. For example, the version 0 promoted_tweet_timeline_impressions, promoted_tweet_search_impressions, and promoted_tweet_profile_impressions metrics are now pre-aggregated and returned simply as impressions when placement is set to ALL_ON_TWITTER. All available placement values are listed in our Ads Enumerations page under the Analytics - V1 section. Do note that placement takes in a single value, so separate queries are required to fetch analytics data for placement on Twitter and placement on the Twitter Audience Platform.

Changes to start_time and end_time

The start_time and end_time parameters are now required for all analytics queries. In addition, all values passed to start_time and end_time must be at whole hours (0 minutes and 0 seconds) across all granularities.

Example

Version 0

In version 0 of analytics, to fetch engagement and billing metrics for a particular Tweet Engagement campaign, the following metrics would need to be explitly queried on the campaign analytics endpoint GET stats/accounts/:account_id/campaigns/:id. Note that a separate engagement metric exists for each type of placement. Also note that no end_time is required in v0.

v0 Metrics:

  • promoted_tweet_timeline_engagements
  • promoted_tweet_timeline_impressions
  • promoted_tweet_timeline_retweets
  • promoted_tweet_timeline_replies
  • promoted_tweet_timeline_favorites
  • promoted_tweet_timeline_follows
  • promoted_tweet_timeline_card_engagements
  • promoted_tweet_timeline_clicks
  • promoted_tweet_timeline_url_clicks
  • promoted_tweet_search_engagements
  • promoted_tweet_search_impressions
  • promoted_tweet_search_retweets
  • promoted_tweet_search_replies
  • promoted_tweet_search_favorites
  • promoted_tweet_search_follows
  • promoted_tweet_search_card_engagements
  • promoted_tweet_search_clicks
  • promoted_tweet_search_url_clicks
  • promoted_tweet_profile_engagements
  • promoted_tweet_profile_impressions
  • promoted_tweet_profile_retweets
  • promoted_tweet_profile_replies
  • promoted_tweet_profile_favorites
  • promoted_tweet_profile_follows
  • promoted_tweet_profile_card_engagements
  • promoted_tweet_profile_clicks
  • promoted_tweet_profile_url_clicks
  • billed_engagements
  • billed_charge_local_micro

v0 Analytics Query:

https://ads-api.twitter.com/0/stats/accounts/abc123/campaigns/def456?start_time=2016-02-01T15:00:00Z&granularity=TOTAL&metrics=promoted_tweet_timeline_engagements,promoted_tweet_timeline_impressions,promoted_tweet_timeline_retweets,promoted_tweet_timeline_replies,promoted_tweet_timeline_favorites,promoted_tweet_timeline_follows,promoted_tweet_timeline_card_engagements,promoted_tweet_timeline_clicks,promoted_tweet_timeline_url_clicks,promoted_tweet_search_engagements,promoted_tweet_search_impressions,promoted_tweet_search_retweets,promoted_tweet_search_replies,promoted_tweet_search_favorites,promoted_tweet_search_follows,promoted_tweet_search_card_engagements,promoted_tweet_search_clicks,promoted_tweet_search_url_clicks,promoted_tweet_profile_engagements,promoted_tweet_profile_impressions,promoted_tweet_profile_retweets,promoted_tweet_profile_replies,promoted_tweet_profile_favorites,promoted_tweet_profile_follows,promoted_tweet_profile_card_engagements,promoted_tweet_profile_clicks,promoted_tweet_profile_url_clicks,billed_engagements,billed_charge_local_micro"

Version 1

In Analytics v1, the same metrics can be fetched with a signicantly simplified request to either the synchronous or asynchronous analytics endpoint. Note that end_time is now a required parameter.

v1 Metric Groups: * ENGAGEMENT * BILLING

v1 Placement: * ALL_ON_TWITTER

v1 Analytics Query:

https://ads-api.twitter.com/1/stats/accounts/abc123?entity_ids=def456&entity=CAMPAIGN&start_time=2016-02-01T15:00:00Z&end_time=2016-02-01T17:00:00Z&granularity=TOTAL&metric_groups=ENGAGEMENT,BILLING&placement=ALL_ON_TWITTER"