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

## Introduction

X (Twitter) Public pulls publicly visible profile and tweet metrics for X (formerly Twitter) accounts that a workspace designates as monitoring targets. The account holder signs in to X through OAuth so requests can be issued against X's official v2 API; the data returned is the public state of the monitored handles, not data restricted to the connecting account.

The connector is intended for competitive monitoring, brand-mention tracking, and influencer analytics. It was originally backed by a third-party scraper and has since been migrated to X API v2. A compatibility mapper rewrites the v2 response into the original field shape, so widgets and dashboards built against the earlier version continue to render without changes.

As a public-data connector, engagement metrics and profile attributes are standardized so widgets can aggregate alongside owned-account sources without additional configuration.

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

## Data refresh strategy

### Architecture data

The list of monitored X handles is configured per data source. Multiple handles can be tracked per data source, and changes to the handle list take effect on the next scheduled refresh. The first sync after a data source is created backfills approximately one year of public tweet history for each monitored handle, subject to the limits of the connected X API tier.

### Reports data

This connector follows a simple-cache pattern: every day, for each monitored handle, data is refetched and the cache is overwritten. The default refresh runs daily at **02:00 UTC**. Ongoing fetches use a rolling date-range window to keep recent activity current. Public counts such as followers and total tweets are stored as snapshot values per refresh.

Manual refresh is available from the connection page, capped at **one per day** per data source.

## Architecture levels

Data source → Monitored handle → Tweet

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

### Tweet engagement

| Metric       | Description                                                    | Data type | API Key         |
| ------------ | -------------------------------------------------------------- | --------- | --------------- |
| Likes        | Like count for the tweet.                                      | Number    | `likeCount`     |
| Reposts      | Repost (retweet) count for the tweet.                          | Number    | `retweetCount`  |
| Replies      | Reply count for the tweet.                                     | Number    | `replyCount`    |
| Quote tweets | Quote-tweet count for the tweet.                               | Number    | `quoteCount`    |
| Bookmarks    | Number of times the tweet was bookmarked.                      | Number    | `bookmarkCount` |
| Impressions  | Times the tweet was shown. Available only on paid X API tiers. | Number    | `viewCount`     |

### Profile snapshots

| Metric           | Description                                               | Data type | API Key           |
| ---------------- | --------------------------------------------------------- | --------- | ----------------- |
| Followers        | Public follower count for the monitored handle.           | Number    | `followers`       |
| Following        | Number of accounts the monitored handle follows.          | Number    | `following`       |
| Tweets published | Total tweets published by the monitored handle.           | Number    | `statusesCount`   |
| Likes given      | Total tweets the monitored handle has liked.              | Number    | `favouritesCount` |
| Listed count     | Number of public lists that include the monitored handle. | Number    | `listedCount`     |
| Media count      | Number of media items the monitored handle has posted.    | Number    | `mediaCount`      |

## Breakdowns

### Tweet breakdowns

| Breakdown                  | Description                                            | API Key                    |
| -------------------------- | ------------------------------------------------------ | -------------------------- |
| Tweet                      | Individual tweet published by the monitored handle.    | `tweetId`                  |
| Author ID                  | X-assigned identifier of the tweet's author.           | `authorId`                 |
| Author username            | Handle of the tweet's author.                          | `authorUserName`           |
| Full text                  | Full text of the tweet.                                | `fullText`                 |
| Language                   | Language of the tweet (BCP 47 tag).                    | `lang`                     |
| Source                     | Client application the tweet was posted from.          | `source`                   |
| Published at               | Date the tweet was published.                          | `createdAt`                |
| Conversation ID            | Identifier of the conversation the tweet belongs to.   | `conversationId`           |
| Quoted tweet ID            | Identifier of the tweet being quoted.                  | `quoteId`                  |
| In reply to (tweet)        | Identifier of the tweet being replied to.              | `inReplyToId`              |
| In reply to (user ID)      | Identifier of the user being replied to.               | `inReplyToUserId`          |
| In reply to (username)     | Handle of the user being replied to.                   | `inReplyToUsername`        |
| Is reply                   | Whether the tweet is a reply.                          | `isReply`                  |
| Is repost                  | Whether the tweet is a repost (retweet).               | `isRetweet`                |
| Is quote                   | Whether the tweet quotes another tweet.                | `isQuote`                  |
| Is pinned                  | Whether the tweet is pinned to the profile.            | `isPinned`                 |
| Is conversation controlled | Whether reply permissions on the tweet are restricted. | `isConversationControlled` |
| Tweet URL                  | Link to the tweet on x.com.                            | `url`                      |
| Tweet URL (twitter.com)    | Link to the tweet on twitter.com.                      | `twitterUrl`               |
| Media                      | First media item attached to the tweet.                | `media`                    |

### Profile breakdowns

| Breakdown                  | Description                                                | API Key                          |
| -------------------------- | ---------------------------------------------------------- | -------------------------------- |
| Monitored handle           | Public X handle the row belongs to.                        | `userName`                       |
| User ID                    | X-assigned identifier for the monitored account.           | `userId`                         |
| Display name               | Display name of the monitored account.                     | `name`                           |
| Description                | Profile bio of the monitored account.                      | `description`                    |
| Location                   | Location listed on the profile.                            | `location`                       |
| Verified                   | Whether the account is verified.                           | `isVerified`                     |
| Protected                  | Whether the account is protected (private).                | `protected`                      |
| Professional type          | Professional account type.                                 | `professional.professional.type` |
| Professional category ID   | Identifier of the account's primary professional category. | `professional.category.id`       |
| Professional category name | Name of the account's primary professional category.       | `professional.category.name`     |
| Professional rest ID       | Professional profile identifier.                           | `professional.rest.id`           |
| Account created at         | Date the monitored account was created.                    | `createdAt`                      |
| Profile picture            | Profile picture of the monitored account.                  | `profilePicture`                 |
| Cover picture              | Cover (header) image of the monitored account.             | `coverPicture`                   |
| Profile URL                | Link to the profile on x.com.                              | `url`                            |
| Profile URL (twitter.com)  | Link to the profile on twitter.com.                        | `twitterUrl`                     |

## Limitations

* **500-tweet cap** — Adriel caps data at up to 500 tweets per monitored handle; this is a connector-set limit.
* **Protected accounts return no data** — private (protected) X accounts cannot be monitored, because X's API does not expose their data even to an authenticated caller. Switching a monitored handle to protected stops new data from arriving; cached history remains queryable.
* **Profile counts are daily snapshots** — follower, following, listed, and similar counts are captured at refresh time and stored as daily snapshots. There is no historical backfill for profile-level counts from before the handle was added.
* **API tier gates available metrics** — the free tier of X API v2 exposes a limited set of metrics. Paid tiers unlock historical impressions, granular engagement, and longer date ranges. The connector reflects whatever the connecting account's API tier returns ([X API](https://developer.x.com/en/docs/x-api)).
* **Rate-limit pressure** — X API v2 enforces low per-window request quotas on lower tiers. Monitoring many handles, or refreshing frequently, can hit these limits and surface as stale or partial data ([X API](https://developer.x.com/en/docs/x-api)). The one-per-day manual refresh quota exists for this reason.

## API references

* Data is retrieved through the X API v2 user-lookup and tweet-timeline endpoints. See the [X API v2 documentation](https://developer.x.com/en/docs/x-api).

## See also

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