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_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.
- Synchronous Analytics: GET stats/accounts/:account_id
- Asynchronous Analytics: POST stats/jobs/accounts/:account_id
For more details on these two endpoints and the differences in each, see the Analytics Overview
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.
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
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_profile_impressions metrics are now pre-aggregated and returned simply as
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.
end_time parameters are now required for all analytics queries. In addition, all values passed to
end_time must be at whole hours (0 minutes and 0 seconds) across all granularities.
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 Analytics Query:
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: *
v1 Placement: *
v1 Analytics Query: