X (Twitter) Ads Data Connector

Follow
Avatar
Vaibhav Gupta
Updated
Setting Up X Ads
Cost Aggregation
Set up data connector
Ad Mon Aggregation
Not supported
Data Discrepancy
Details coming soon

 

Learn how Singular pulls advertising cost data from X Ads (formerly Twitter) and displays it in your reports. You will still find Twitter noted as the source for X Ads campaign data in Singular's dashboard.

 

Quick Details

Data Connector Technology API (X Ads API version 11 - see documentation)
Data breakdown (segmentation)

Data from X Ads (Twitter) is always broken down by:

  • Campaign
  • Sub-campaign (line item)

In addition, you can get one of the following breakdowns:

  • Platform (default)
  • DMA Name
  • Age
  • Gender

If you're interested in getting geographic location instead of platform breakdown, reach out to your Customer Success Manager or Singular support and specify whether you want the user's DMA.

Note: X Ads does not provide publisher breakdown.

X Ads no longer supports City or Region breakdowns.
How far back we pull data 30 days
Time zone Defined by the customer per account
Is data available on the creative level? Yes
Does Singular show your creative assets? Yes - including images, videos, and streaming videos.
Singular does not show Polls.
Known Limitations/ Issues
 
  • X Ads does not provide Publisher breakdown.
  • Singular can't show Scheduled Tweets before the tweet is live. We pull them when/if they go live.
  • There are no install statistics per creative.
  • Metrics on the Creative level do not always match metrics pulled on the Sub-Campaign level (X Ad's Line Item).
  • There may be discrepancies between X’s platform breakdown report and X’s country breakdown report.

To learn more about internal discrepancies in X Ads data, see X Ad's article on the subject.

Data Mapping

Terminology Notes:

  • Sub-Campaign in Singular corresponds to X Ads's Line Item.
  • Creative in Singular can correspond to X Ads's Tweet, Promoted Tweet, Card, or Media Creative. 
  • Metrics are pulled from X Ads's Line Item, Promoted Tweet, and Media Creative objects.
  • The geographic location dimensions (Country, DMA Name) are available only if you've requested to get location instead of platform breakdown (see "Data breakdown" above).

For a description of each field in Singular, see Metrics and Dimensions.

Field in Singular UI Field in Singular API Field in X Ads API
Dimensions
Account ID adn_account_id Account_object: id
Account Name adn_account_name Account_object: name
Agency agency Not pulled directly from X Ads, but Singular can set the agency per each account.
App Site ID app_site_id Estimated based on any URLs available in creative-related objects (Tweets,  Promoted Tweets, Cards, Media Creatives, Account Medias). If not possible, we try to estimate based on campaign URLs and Line Item URLs.
Campaign URL adn_campaign_url
  • Pulled from a Card object related to a Tweet related to a Line Item in the campaign.
  • The field is "website_dest_url" in X Ads API v. 6.0 but if that is not populated we look under old field names: “website_url", "website_shortened_url", "media_url". 
  • If there was no Card, we look for the "landing_url" field in a Media Creative object.
Country country_field We query the X Ads API with segment_by=”LOCATIONS”, and take the segment name for each Line Item and Promoted Tweet.
Creative Reported URL creative_reported_url  
Date date_field Since the Singular data connector pulls daily reports, we add the date ourselves.
DMA Name
 		 dma_name_field
 		 Same as Campaign URL
Network Campaign ID adn_campaign_id "id" in the Campaign object
Network Campaign Name adn_campaign_name "name" in the Campaign object
Network Creative ID adn_creative_id

Depends on the type of the creative.

  • If the creative is a Promoted Tweet: "tweet_id" in the Promoted Tweet object
  • If the creative is a Media Creative: "id" in the Account Media object.
Network Creative Name adn_creative_name Take the "media id" from the Card object and query X Ads for the media "name".
Network Sub Campaign ID adn_sub_campaign_id "id" in the Line Item object
Network Sub Campaign Name adn_sub_campaign_name "name" in the Line item object
Placement
 		 placement
 		 placements (possible values: ALL_ON_TWITTER, PUBLISHER_NETWORK, TWITTER_PROFILE, TWITTER_SEARCH, TWITTER_TIMELINE, TAP_BANNER, TAP_FULL, TAP_FULL_LANDSCAPE, TAP_NATIVE, TAP_MRECT)
Platform platform
  • This is only available if you have asked Singular to receive the Platform breakdown instead of the Country breakdown.
  • We query the Twitter API with segment_by=”PLATFORMS”, and take the segment name for each Line Item and Promoted Tweet.
Public Id site_public_id "googleplay_app_id" or "iphone_app_id" in the Card object, if available.
Sub Ad Network adn_subadnetwork
  • Set to "twitterfeed" if the data was queried from "ALL_ON_TWITTER"
  • Set to "twittertpn" if the data was queried from "PUBLISHER_NETWORK"
Target Countries target_countries_str For each sub-campaign (line item), we pull "countries" from the /targeting_criteria endpoint. We concatenate the results into this field.
Text creative_text Depending on the type of the creative, either "name" from the Card object, "text" from the Tweet object, or "media_name" from the Account Media.
Timezone adn_timezone "timezone" in the Account object
Age age AGE
Gender gender GENDER
Metrics
Comments
 		 comments replies
Likes
 		 likes likes
Network Clicks adn_clicks “clicks”
Network Impressions adn_impressions "impressions"
Network Installs adn_installs "mobile_conversion_installs"
Original Cost adn_original_cost "billed_charge_local_micro"
Original Currency adn_original_currency “currency” in the Campaign object
Page Follows
 		 page_follows follows
Shares
 		 shares retweets
Video Views video_views “video_total_views”
Completed Video Views completed_video_views “video_views_100”
Video Views - 25% video_views_25pct “video_views_25”
Video Views - 50% video_views_50pct “video_views_50”
Video Views - 75% video_views_75pct “video_views_75”

Singular also supports pulling campaign properties for this partner - please see more details here.