Introduction

Analytics metrics help partners and advertisers understand the performance of the content they promote on Twitter. This includes information such as impressions, clicks, video views, and spend. In addition, partners and advertisers are able to get detailed metrics for various segments of the audiences they reach.

The Ads API supports two ways of retrieving detailed campaign performance metrics: synchronously and asynchronously. With synchronous analytics calls, the requested metrics are returned in the response. With the asynchronous analytics endpoints, the requested metrics are available in a downloadable results file after the associated "job" has finished processing. The synchronous endpoint supports short time ranges and is ideal for real-time campaign optimizations. The asynchronous endpoints support much longer time ranges and are, thus, intended for fetching much more data, ideal for generating reporting or historical backfills.

Details

Synchronous vs. Asynchronous

The differences between the synchronous and asynchronous analytics endpoints are summarized in the following table. This information is intended to help developers choose which set of endpoints to use.

  Synchronous Asynchronous
Rate limiting User-level: 250 requests / 15 minutes Account-level: 100 concurrent* jobs
Time range 7 days 90 days (non-segmented)
45 days (segmented)
Segmentation No Yes
Response returns Metrics data Processing state of the job**
Recommended use case Real-time optimization
User interface requests
Regularly-scheduled syncing
Backfilling historical data

* This refers to the maximum number of jobs that may be in a processing state at any given time.
** Once the job has successfully finished processing, a URL is returned. This is where the compressed (gzip) results file can be downloaded from.

Outside of this, the endpoints offer the same functionality.

Use cases

There are three major analytics use cases.

  1. Real-time optimization: using performance metrics to update active campaigns
  2. Synchronization: regularly-scheduled background syncs
  3. New account on-boarding: backfilling historical data

The synchronous analytics endpoint may be used for real-time optimization to update campaigns based on changes to metrics within the last 5 to 15 minutes. Either endpoint can be used for analytics synchronization. Keep in mind that the desired time range and whether segmentation is required will determine which endpoint to use. New account on-boarding should only be done using the asynchronous analytics endpoints. (The synchronous analytics endpoint should never be used for retrieving large amounts of data.)

The asynchronous analytics endpoints can power dashboards and other UI elements if metrics are synced with a backend process. Your implementation should avoid calling the asynchronous analytics endpoints to fulfill user interface requests.

Request Options

Analytics requests are scoped to ads accounts and, thus, require the account ID in the resource path. Request options, listed below, are specified as query parameters. The following types of values are required.

  • Entities: the entity type as well as up to 20 entity IDs you'd like to request analytics for
  • Time range: the start and end times, expressed in ISO 8601
    • Note: must be expressed in whole hours
  • Metric groups: one or more sets of related metrics (see Metrics and Segmentation for a list of metrics within each metric group)
  • Granularity: specifies the level of aggregation in which the metrics should be returned
  • Placement: determines whether metrics are pulled for ads that served on or off of Twitter
    • Note: only a single placement value can be specified per request

Use the start_time and end_time request parameters to specify a time range. These values must be aligned with the specified granularity in the following way.

  1. TOTAL: specify any time range (within the endpoint's limits)
  2. DAY: both the start time and end time values must be aligned with midnight in the account's time zone
  3. HOUR: specify any time range (within the endpoint's limits)

End time is exclusive. For example, a request with start_time=2019-01-01T00:00:00Z and end_time=2019-01-02T00:00:00Z will return a single day's worth of analytics metrics (not two) as this time range covers only a 24 hour period.

Segmentation

Available only through our asynchronous analytics endpoints, segmentation allows partners and advertisers to retrieve metrics broken out particular targeting values. To request segmented metrics, use the segmentation_type request parameter. For more details on segmentation options, see Metrics and Segmentation.

FAQs

Why don't the Ads API numbers match what's shown in the Twitter Ads UI?

  • Make sure you've requested data for both placements: ALL_ON_TWITTER and PUBLISHER_NETWORK
  • Remember that end times in the Ads API are exclusive; they are inclusive in the Ads UI

How can I determine which entity IDs to request for a specific time period?

How can I request metrics associated with a granular placement, such as the Twitter timeline?

  • We only support two placement values in analytics: ALL_ON_TWITTER and PUBLISHER_NETWORK (i.e., the Twitter Audience Platform)

Why don't the segmented values match the non-segmented ones?

  • Segmented data is not expected to roll-up 100% to the non-segmented data, due to how this information is derived.

Is it possible to request data segmented by multiple dimensions?

  • We do not support multi-segmentation