> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the X (Twitter) Ads data source in Adriel.

## 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-sources/o-z/x-twitter-ads/how-to-connect).

## 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.

<Note>
  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.
</Note>

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

<Note>
  **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.
</Note>

### 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)

<Note>
  `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.
</Note>

### 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

<Note>
  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).
</Note>

| 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

<Note>
  Channel is an Adriel-provided constant label used for cross-connector rollup.
</Note>

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

### UTM tracking

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

| 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

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

| 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

* [X Ads API documentation](https://developer.x.com/en/docs/x-ads-api)
* [X Ads API — Analytics](https://developer.x.com/en/docs/x-ads-api/analytics)
* [X Ads API — Metrics and segmentation](https://developer.x.com/en/docs/x-ads-api/analytics/api-reference/metrics-and-segmentation)

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

## See also

* [How to connect X (Twitter) Ads to Adriel](/data-sources/o-z/x-twitter-ads/how-to-connect) (paired how-to)
* [X (Twitter) Organic data reference](/data-sources/o-z/x-twitter-organic/data-reference) — for organic profile metrics
* [Meta Ads data reference](/data-sources/g-n/meta-ads/data-reference) — for paid social attribution comparison