Introduction

Analytics metrics help partners and advertisers understand the performance of the content they promote on X. 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.

* 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 X
  • 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 X 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

Why do the numbers change depending on when I request data?

• As soon as reporting metrics are available, you are able to retrieve them. They are available in near real-time. These early results are estimates, though, and, as a result, are expected to change. Metrics are finalized after 24 hours, with the exception of spend data.
• Spend metrics are generally final within 3 days of the event. However, we process billing data for up to 14 days from the date of the event (for spam filtering, for example).

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

• Use the Active Entities endpoint

Why are all of the values in the analytics response null?

• It's likely that the campaign did not serve during during the requested time period
• Use the Active Entities endpoint to determine which entities to fetch analytics for and for what time period

Why does the API show null values while the UI shows 0s?

• The UI chooses to display these values as 0s, but the values are equivalent

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

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

Is it possible to retrieve metrics for deleted or paused entities?

• Yes. The entity's status does not impact the availability of analytics metrics.

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