Data reference - Adriel Knowledge Base

Introduction

X (Twitter) Ads is X’s paid advertising platform, used to promote posts, accounts, trends, and app-install campaigns across the X timeline, search, and profile placements. The platform supports CPM, CPC, CPE (cost per engagement), and CPV payment models across awareness, consideration, and conversion objectives. The connector imports campaign structure, performance metrics, and conversion data through the X Ads API. As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration. To connect this data source, see How to connect X (Twitter) Ads to Adriel.

Data refresh strategy

Architecture data

Architecture covers ad accounts, campaigns, ad sets, and ads. It refreshes twice daily at 4:00 PM UTC and 5:00 AM UTC. On data source creation, the cache fills with 365 days of historical data for the ad account, campaign, ad set, and ad levels.

Reports data

Reports include daily performance metrics for ad accounts, campaigns, ad sets, and ads, plus per-ad-account breakdowns for age, gender, location, country, OS, device target, and hour of day. Cache-only. Reports are submitted as asynchronous jobs to the X Ads API, polled until ready, and cached. Dashboard queries always read from the last snapshot, never live from X.

Metrics based on uniqueness (such as reach) can be overvalued when viewed for a date period longer than one day, because uniqueness is computed per snapshot rather than across the full range.

Refresh schedule. Reports refresh on several overlapping schedules:

7:30 PM UTC — syncs the last 9 days for age, gender, location, country, OS, and device target (all per ad account)
5:00 PM UTC — syncs the last 9 days for campaign, ad set, ad, and hour of day (per ad account)
9:00 PM, 6:00 AM, and 11:00 AM UTC — syncs the last 3 days for campaign, ad set, ad, and hour of day (per ad account)
3:00 AM and 8:00 AM UTC — syncs the last 1 day for campaign, ad set, ad, and hour of day (per ad account)
3:00 PM UTC, on day 3 of each month — syncs the last 35 days for campaign, ad set, ad, plus all per-ad-account demographic, geo, device, and hour breakdowns

Data is reliable within the cache sync period. Data outside this range may be incomplete or inaccurate due to legacy caching behavior.

Architecture levels

Ad account → Campaign → Ad set → Ad

Date range limits

Breakdown	Max range
Daily	93 days
Weekly	1 year
Monthly	2 years

Metrics

How to read the columns Data type uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean. API Key in code style like impressions is the literal X Ads API field name. Italic text describes how a value is produced when it doesn’t map cleanly to a single API field.

Performance

Metric	Description	Data type	API Key
Impressions	Total times the posts were displayed.	Number	`impressions`
Qualified impressions	Impressions meeting X’s quality criteria.	Number	`qualified_impressions`
Clicks (all)	Total clicks.	Number	`clicks`
URL clicks	Clicks that led to a URL.	Number	`url_clicks`
App clicks	Clicks on app-install ads.	Number	`app_clicks`
Engagements	Any user interaction, such as clicks, likes, or reposts.	Number	`engagements`
Billed engagements	Engagements that were charged for.	Number	`billed_engagements`
CTR	Click-through rate.	Percentage	Adriel-computed (clicks ÷ impressions)
CPM	Cost per thousand impressions.	Currency	Adriel-computed (spend ÷ impressions × 1000)
CPC	Cost per click.	Currency	Adriel-computed (spend ÷ clicks)
Ad spend	Total amount spent. Stored as microcurrency and divided by 1,000,000.	Currency	`billed_charge_local_micro`

Engagement

Metric	Description	Data type	API Key
Likes	Likes on the ad.	Number	`likes`
Retweets	Reposts.	Number	`retweets`
Replies	Replies to the ad.	Number	`replies`
Follows	New follows.	Number	`follows`
Unfollows	Unfollows.	Number	`unfollows`
Tweets sent	Promoted posts sent.	Number	`tweets_send`
Card engagements	Engagements with card units.	Number	`card_engagements`
Carousel swipes	Carousel ad swipes.	Number	`carousel_swipes`
Media engagements	Engagements on media within the ad.	Number	`media_engagements`
Media views	Views of media.	Number	`media_views`
Poll card votes	Votes on poll cards.	Number	`poll_card_vote`

Video performance

Metric	Description	Data type	API Key
Video impressions	Video content starts.	Number	`video_content_starts`
Total video views	Total video views.	Number	`video_total_views`
Video views at 25% / 50% / 75% / 100%	Views reaching each named completion threshold.	Number	`video_views_25` / `_50` / `_75` / `_100`
3s/100% video views	Views of at least 3 seconds or 100% completion.	Number	`video_3s100pct_views`
6s video views	Views of at least 6 seconds.	Number	`video_6s_views`
15s video views	Views of at least 15 seconds.	Number	`video_15s_views`
Video CTA clicks	Clicks on the video CTA.	Number	`video_cta_clicks`

Conversion performance — web

Web conversions are nested by attribution sub-type. Each base event exposes count metrics by sub-type (post_view, post_engagement, order_quantity, sale_amount) and a _value variant where applicable. Count metrics are reported as a Number and value metrics as a Currency. Base events:

conversion_purchases (the only event where the metric sub-field is exposed)
conversion_sign_ups
conversion_site_visits
conversion_downloads
conversion_custom
auto_created_conversion_landing_page_view (auto-created)
auto_created_conversion_session (auto-created)

conversion_purchases is the only event with a metric sub-field. All other nested conversion metrics skip the metric sub-type during mapping, because that field had data discrepancies for non-purchase events.

Conversion performance — mobile (MMP)

Mobile conversions are similarly nested by sub-type, reported as a Number for counts and a Currency for value variants. Base events:

App lifecycle: mobile_conversion_installs, mobile_conversion_logins, mobile_conversion_re_engages, mobile_conversion_updates
Commerce: mobile_conversion_purchases, mobile_conversion_add_to_carts, mobile_conversion_add_to_wishlists, mobile_conversion_checkouts_initiated, mobile_conversion_payment_info_additions, mobile_conversion_reservations
Engagement: mobile_conversion_content_views, mobile_conversion_searches, mobile_conversion_shares, mobile_conversion_invites, mobile_conversion_levels_achieved, mobile_conversion_achievements_unlocked, mobile_conversion_tutorials_completed, mobile_conversion_key_page_views
Other: mobile_conversion_downloads, mobile_conversion_sign_ups, mobile_conversion_site_visits, mobile_conversion_spent_credits, mobile_conversion_rates

Each base event also has corresponding _lifetime_value_* suffix variants for lifetime-value reporting.

Custom conversion events

For each conversion event configured in the connected X Ads account, the following derived metrics are generated. [event_name] is replaced by the configured event name.

Metric	Description	Data type	API Key
`X (Twitter) Ads: [event_name]`	Count of the conversion event.	Number	Resolved from X conversion events API
`X (Twitter) Ads: [event_name]: Conversion value`	Monetary value of the conversion event.	Currency	Resolved from X conversion events API
`X (Twitter) Ads: [event_name]: CPA`	Cost per action.	Currency	Adriel-computed (spend ÷ count)
`X (Twitter) Ads: [event_name]: ROAS`	Return on ad spend.	Ratio	Adriel-computed (value ÷ spend)
`X (Twitter) Ads: [event_name]: CVR`	Conversion rate.	Percentage	Adriel-computed (count ÷ clicks × 100%)

UTM tracking

UTM values are parsed by Adriel, not returned by X. Adriel reads the UTM query parameters from each ad’s configuration and landing URL, and exposes them as both metrics (for rollup) and breakdowns (for grouping).

Metric	Description	Data type	API Key
UTM Source	Parsed `utm_source` parameter.	Text	Adriel-parsed from ad configuration or landing URL
UTM Medium	Parsed `utm_medium` parameter.	Text	Adriel-parsed
UTM Campaign	Parsed `utm_campaign` parameter.	Text	Adriel-parsed
UTM Content	Parsed `utm_content` parameter.	Text	Adriel-parsed
UTM Term	Parsed `utm_term` parameter.	Text	Adriel-parsed

Campaign structure metadata

Metric	Description	Data type	API Key
Ad account name	Name of the ad account.	Text	`name`
Campaign name	Campaign name.	Text	`name`
Ad set name	Ad set (line item) name.	Text	`name`
Ad name	Ad name, resolved through a fallback chain (post name, card name, full text).	Text	`name`, with fallbacks
Status	Entity and effective status.	Text	`entity_status`, `effective_status`
Creative URL	Preview URL for media on the promoted post.	URL	Resolved from post media metadata

Breakdowns

Standard hierarchy

Breakdown	Description	API Key
Ad account	Group by ad account.	`name`
Campaign	Group by campaign.	`name`
Ad set	Group by ad set.	`name`
Ad	Group by ad.	`name`

Demographics & geography

Available per ad account.

Breakdown	Description	API Key
Age	Audience age.	X demographic segment
Gender	Audience gender.	X demographic segment
Country	Country.	X geo segment
Location	Geographic region.	X geo segment

Device & time

Available per ad account.

Breakdown	Description	API Key
OS	Operating system.	X device segment
Device target	Targeted device.	X device segment
Hour of day	Hour in the advertiser’s time zone.	X time segment

Channel

Channel is an Adriel-provided constant label used for cross-connector rollup.

Breakdown	Description
Channel	Constant source label for X (Twitter) Ads.

UTM tracking

X doesn’t return UTM values; Adriel parses them from each ad’s configuration and landing URL and exposes them as breakdowns for grouping.

Breakdown	Description
UTM Source	Group by parsed `utm_source`.
UTM Medium	Group by parsed `utm_medium`.
UTM Campaign	Group by parsed `utm_campaign`.
UTM Content	Group by parsed `utm_content`.
UTM Term	Group by parsed `utm_term`.

Time grouping

Time-grouping breakdowns are Adriel-side aggregations of the same underlying daily report data.

Breakdown	Description
Auto Time Breakdown	Automatically picks the best granularity for the date range.
Daily	Split reports by day.
Weekly	Split reports by week.
Monthly	Split reports by calendar month.
Quarterly	Split reports by calendar quarter.
Yearly	Split reports by calendar year.

Limitations

Cache-only reporting — dashboards read from the last cached snapshot, never live from X. Values are reliable within the cache sync period; data outside it may be incomplete or inaccurate.
Reach across long date ranges may be overvalued — because uniqueness is computed per snapshot, reach aggregated across multi-day windows can overstate true unique reach.
Ad set and ad pagination not implemented — when the X API returns a next_cursor for ad sets or ads (meaning more entities than fit in one page), the architecture fetch throws a “pagination is not implemented” error. This is rare in practice but is a hard limit on very large accounts.
Default currency USD on empty accounts — ad accounts without any campaigns default to USD instead of deriving currency from campaign data. Once campaigns exist, the configured currency is used.
Microcurrency conversion — spend is reported by X in microcurrency units and is divided by 1,000,000 during parsing.
Token revocation, not expiry — OAuth 1.0a tokens don’t expire automatically but can be revoked. Reconnect via Connections → X (Twitter) Ads → Reconnect if access is lost.

API references

API base: https://ads-api.twitter.com/12/ (X Ads API v12).

​Introduction

​Data refresh strategy

​Architecture data

​Reports data

​Architecture levels

​Date range limits

​Metrics

​Performance

​Engagement

​Video performance

​Conversion performance — web

​Conversion performance — mobile (MMP)

​Custom conversion events

​UTM tracking

​Campaign structure metadata

​Breakdowns

​Standard hierarchy

​Demographics & geography

​Device & time

​Channel

​UTM tracking

​Time grouping

​Limitations

​API references

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Metrics

Performance

Engagement

Video performance

Conversion performance — web

Conversion performance — mobile (MMP)

Custom conversion events

UTM tracking

Campaign structure metadata

Breakdowns

Standard hierarchy

Demographics & geography

Device & time

Channel

UTM tracking

Time grouping

Limitations

API references

See also