> ## 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) Organic data source in Adriel.

## Introduction

X (Twitter) Organic surfaces account-level and post-level organic performance for a connected X account. It covers published posts, post engagement, video performance, and audience signals such as follower and following counts — the unpaid activity on an account, separate from any paid campaigns.

<Note>
  This data source uses the v2 X Organic connector. The earlier v1 connector is deprecated: existing v1 widgets keep working, but the v1 connector is hidden from new-connection flows.
</Note>

As an organic-social connector, engagement metrics and post-level breakdowns are standardized so widgets can aggregate alongside other sources without additional configuration.

To connect this data source, see [How to connect X (Twitter) Organic to Adriel](/data-sources/o-z/x-twitter-organic/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers the X account and its posts. It refreshes daily at 6:30 PM UTC. On first connection, posts created within the last 180 days are retrieved, but only lifetime totals are available for them — there are no historical daily values for posts published before the connection. Metrics accumulate in the cache from the connection date forward, and new posts appear after the next daily refresh.

### Reports data

Reports include daily performance for the account and its posts. This connector is cache-based: dashboards read from the daily cache that these scheduled refreshes maintain.

* **Lifetime account and post data** refreshes daily at 6:30 PM UTC.
* **Daily page data** is initially backfilled for the last 180 days; each cycle then refreshes the most recent 3 days at 6:00 PM UTC.

Follower-type metrics have no historical backfill — only daily snapshots are cached, starting from the connection date.

## Architecture levels

X account → Post

## 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 field name. *Italic text* describes how a value is produced when it does not map cleanly to a single API field.
</Note>

<Note>
  **Lifetime and delta values**
  X returns a snapshot of each post's totals at the moment of retrieval. Adriel caches those snapshots once per day so it can report both lifetime values (the running total) and delta values (the day-over-day change, useful for trend charts). For posts published before the connection date, the first delta is 0 because no earlier snapshot exists, so the sum of deltas will not match the lifetime total for those posts.
</Note>

### Profile and followers

| Metric             | Description                                    | Data type | API Key                                   |
| ------------------ | ---------------------------------------------- | --------- | ----------------------------------------- |
| Follower count     | Cumulative followers of the connected account. | Number    | `followers_count`                         |
| Following count    | Accounts the connected account follows.        | Number    | `follows`                                 |
| Post count         | Posts published by the account.                | Number    | *Adriel-computed (count of cached posts)* |
| Account favourites | Posts the account has liked (favourited).      | Number    | `favourites_count`                        |

### Impressions

| Metric                | Description                                       | Data type | API Key                 |
| --------------------- | ------------------------------------------------- | --------- | ----------------------- |
| Post impressions      | Number of times posts were shown.                 | Number    | `impressions`           |
| Qualified impressions | Impressions that met X's qualified-view criteria. | Number    | `qualified_impressions` |

### Engagement

| Metric                | Description                                  | Data type  | API Key                                       |
| --------------------- | -------------------------------------------- | ---------- | --------------------------------------------- |
| Post engagement       | Total engagements on posts.                  | Number     | `engagements`                                 |
| Post likes            | Likes on posts.                              | Number     | `likes`                                       |
| Post reposts          | Reposts of posts (formerly retweets).        | Number     | `retweets`                                    |
| Post replies          | Replies to posts.                            | Number     | `replies`                                     |
| Post clicks           | Total clicks on posts.                       | Number     | `clicks`                                      |
| Post URL clicks       | Clicks on links within posts.                | Number     | `url_clicks`                                  |
| Post app clicks       | Clicks to open or install an app from posts. | Number     | `app_clicks`                                  |
| Post card engagements | Engagements with a post's card.              | Number     | `card_engagements`                            |
| Post carousel swipes  | Swipes on carousel posts.                    | Number     | `carousel_swipes`                             |
| Engagement rate       | Engagements as a share of impressions.       | Percentage | *Adriel-computed (engagements / impressions)* |

### Video

| Metric                             | Description                               | Data type | API Key                                   |
| ---------------------------------- | ----------------------------------------- | --------- | ----------------------------------------- |
| Video views                        | Video views on posts.                     | Number    | `video_views`                             |
| Total video views                  | Total video views on posts.               | Number    | `video_total_views`                       |
| Video views 3s                     | Video views of at least 3 seconds.        | Number    | `video_3s100pct_views`                    |
| Video views 6s                     | Video views of at least 6 seconds.        | Number    | `video_6s_views`                          |
| Video views 15s                    | Video views of at least 15 seconds.       | Number    | `video_15s_views`                         |
| Video views 25% / 50% / 75% / 100% | Views reaching each completion threshold. | Number    | `video_views_25` / `_50` / `_75` / `_100` |
| Video content starts               | Video playback starts.                    | Number    | `video_content_starts`                    |
| Video CTA clicks                   | Clicks on a video's call to action.       | Number    | `video_cta_clicks`                        |

### Post metadata

| Metric     | Description                                          | Data type | API Key           |
| ---------- | ---------------------------------------------------- | --------- | ----------------- |
| Post text  | The post's text content.                             | Text      | `full_text`       |
| Post link  | Expanded URL contained in the post.                  | URL       | `expanded_url`    |
| Post media | Media URL associated with the post.                  | URL       | `media_url_https` |
| Post type  | The post type (for example, original post or reply). | Text      | `tweet_type`      |
| Post date  | Date the post was created (UTC).                     | Date      | `created_at`      |

## Breakdowns

### Account and post

| Breakdown | Description                       | API Key  |
| --------- | --------------------------------- | -------- |
| Account   | Group by the connected X account. | `userId` |
| Post      | Group by individual post.         | `postId` |

### Date

| Breakdown | Description          | API Key |
| --------- | -------------------- | ------- |
| Date      | Daily bucket in UTC. | `date`  |

### Time grouping

<Note>
  These groupings are Adriel-side aggregations of the same underlying daily data.
</Note>

| Breakdown           | Description                                                           |
| ------------------- | --------------------------------------------------------------------- |
| Auto Time Breakdown | Automatically picks the best granularity for the selected 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.                                       |

### Overview

<Note>
  These are Adriel-provided grouping labels used for cross-connector reporting rather than values returned by X.
</Note>

| Breakdown   | Description                                                       |
| ----------- | ----------------------------------------------------------------- |
| Channel     | Constant label used to roll X organic up alongside other sources. |
| No Grouping | Do not break down; return one aggregated row.                     |

## Limitations

* **180-day first-time fetch** — on first connection, only posts created within the last 180 days are retrieved, and those pre-connection posts arrive with lifetime totals only, no historical daily values.
* **No follower history before connection** — follower-type metrics have no historical backfill; daily snapshots begin accumulating from the connection date.
* **Delta baseline** — posts published before the connection date start with a delta of 0, so the sum of deltas will not equal the lifetime total for older posts. When a daily delta cannot be calculated (for example, during API downtime), the value is linearly estimated from the last available snapshot.
* **Page data derived from posts** — account-level metrics are summed from the cached per-post rows rather than fetched from a dedicated account endpoint, so page totals depend on how completely posts synced for the day.
* **Media expiry** — media associated with a post may become unavailable if the post is no longer retrievable through the API.
* **Older or removed posts** — delta values for very old posts (3+ years) or posts that became unretrievable (deleted or restricted) are not recorded.
* **Temporary content** — short-lived content is not fully implemented and may contain missing or inaccurate data.
* **Rate limits** — X enforces strict rate limits on organic analytics endpoints ([X Ads API — Analytics](https://developer.x.com/en/docs/x-ads-api/analytics)); for high-volume accounts a refresh cycle can be partial or delayed. This is a platform constraint rather than a connector behavior.
* **Historical reach** — the Adriel connector makes roughly two years of history available for querying; this is a connector-set limit.

## API references

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

## See also

* [How to connect X (Twitter) Organic to Adriel](/data-sources/o-z/x-twitter-organic/how-to-connect) (paired how-to)
* [X (Twitter) Ads data reference](/data-sources/o-z/x-twitter-ads/data-reference) — for paid X campaigns