Skip to main content

​
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

​
Metrics

How to read the columnsData type uses Adriel’s 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; where the same raw field name is shared across objects (X returns name and id for the ad account, ad, ad set, and campaign), it’s shown qualified as object.field (for example account.name) so each row stays unique; italic marks a value Adriel computes, derives, or parses. Some raw fields back several metrics — notably billed_charge_local_micro (spend) and the video_* view fields — so the same key can appear on multiple rows; that’s the shared source field, not a duplicated entry. Currency values are reported in each ad account’s configured X currency.

​
Basic

​
Campaign Attributes

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 metrics for rollup. X’s reporting API does not return UTM values directly.

​
Campaign Structure

​
Computed Metric

These are calculated by Adriel from other metrics; they have no single underlying X field.

​
Conversion Performance

Conversions come from the configured X conversion events. For each conversion event tracked in the connected X Ads account, Adriel imports a count and, where available, a value. Web events are nested by attribution sub-type (post_view, post_engagement, order_quantity, sale_amount); conversion_purchases is the only event that also exposes the metric sub-field, because that field had data discrepancies for other events. The full per-event web and mobile (MMP) conversion metrics are itemized in the X (Twitter) Ads-specific group below.

​
Creative Attributes

​
Engagement

​
Impression Click Performance

​
Video Performance

​
X (Twitter) Ads-specific

These metrics exist only for X (Twitter) Ads and aren’t part of any cross-connector category. Every group above is a standard category shared with other connectors.

​
Breakdowns

​
Basic

​
Campaign Structure

​
Creatives

Adriel post-processes ad creatives to generate these breakdowns.

​
Date

X’s report data is daily; all time-grouping breakdowns are Adriel-side aggregations of the same underlying daily data.

​
Others

​
X (Twitter) Ads-specific

These breakdowns exist only for X (Twitter) Ads and aren’t part of any cross-connector category. Every group above is a standard category shared with other connectors.
Audience, geography, device, and operating-system breakdowns (Age, Gender, Country, Location, Device Target, Operating System) are available per ad account only.

​
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).

​
See also