Integrating Twitter Ads on Clarisights
X (formerly Twitter) Ads is X Corp's advertising platform for running Promoted Tweets, video, and conversion campaigns on the X timeline and the X Audience Platform. Connecting X Ads to Clarisights lets you blend social ad performance with your other paid channels to compare spend, engagement, video views, and downstream conversions side-by-side.
At a glance
| Authentication | OAuth 1.0a (sign in with X) |
| Permissions needed | Account Admin or Ad Manager role on each X Ads account; the X profile must be allowed to authorize third-party apps |
| Account discovery | Automatic on credential validation — every ads account on the X user is offered |
| Data freshness | Hourly (incremental every ~2 days; full refresh every ~8 days) |
| Lookback window | 8 days on each scheduled run; backfills capped at 30 days per request |
| Backfill on connect | Up to 30 days |
| Timezone | Account-level timezone configured in X Ads |
| Currency | Account native currency (auto-converted via Currency Conversion); conversion values returned in micro-currency are normalized on ingest |
| Levels supported | Account · Campaign · Line Item / Ad Group · Promoted Tweet |
| Limited rollout | No |
Prerequisites
An active X Ads account managed in X Ads Manager
A user role on the account: Account Admin or Ad Manager (Analyst is not sufficient because Clarisights pulls ad-object metadata in addition to reports)
Permission on your X profile to authorize third-party apps
For conversion reporting: web events configured via the X Pixel and/or mobile events configured via a measurement partner (Adjust, AppsFlyer, Branch, etc.)
Steps to Connect
Step 1 — Open the Integrations page
In Clarisights, go to Integrations, find Twitter, and click + Connect.
[TODO: Screenshot needed — Integrations page Twitter row with Connect button]
Step 2 — Sign in with X
You'll be redirected to X to sign in. Use the X account that has Account Admin or Ad Manager access on the X Ads accounts you want to bring into Clarisights.
[TODO: Screenshot needed — X sign-in page]
⚠ "You don't have permission to authorize this app." → The X profile being used has third-party app authorization disabled, or it lacks a qualifying role on the X Ads accounts. Re-attempt with an X user that has Account Admin or Ad Manager access.
Step 3 — Authorize Clarisights
X will display a permissions screen listing the access Clarisights needs (read access on X Ads accounts, campaigns, line items, promoted tweets, and reporting). Click Authorize app.
Do not close or refresh this window — you will be redirected back to Clarisights automatically.
Step 4 — Select accounts to connect
Once you're back on the Integrations page, every X Ads account visible to your X user is listed. Toggle the accounts you want to bring into Clarisights and confirm.
[TODO: Screenshot needed — account selection modal]
Verify the connection
Go to Integrations → Twitter. Each connected X Ads account should show a "Connected" status with the option to enable / disable individual accounts and refresh the OAuth token.
First data appears within ~1 hour of the next scheduled sync.
Quick start: create a new report, add Twitter as the data source, and add Account · Campaign · TW: Impressions · TW: Engagements · TW: Spend.
Data available
Hierarchy
How X Ads' native levels map to the standard Clarisights levels:
Native level (X / Twitter Ads) | Clarisights level |
Account (with Funding Instrument as an attribute) | Account |
Campaign | Campaign |
Line Item | Ad Group |
Promoted Tweet (with Card and Media Creative attributes) | Ad |
Note on Tweet text: we recommend using the Tweet Text dimension over the older Promoted Tweet dimension. Promoted Tweet may carry truncated values when the tweet copy is long; Tweet Text always returns the full copy.
Dimensions
Dimension | Level | Description |
Account ID | Account | X Ads account identifier |
Campaign ID | Campaign | X campaign identifier |
Funding Instrument | Campaign | Payment instrument backing the campaign (credit card, IO, etc.) |
Campaign Status | Campaign | Active, Paused, or Archived |
Ad Group ID | Ad Group | X line item identifier |
Ad Group Status | Ad Group | Active, Paused, etc. |
Line Item Objective | Ad Group | Campaign goal at the line-item level (Engagements, Website Clicks, App Installs, Video Views, etc.) |
Optimization | Ad Group | Optimization preference set on the line item |
Bid Type | Ad Group | Target or Max, depending on the bidding strategy |
Followers | Ad Group | Followers targeting set on the line item |
Placement Network | Ad Group | Placement networks selected (X-only, X Audience Platform) |
Placements | Ad Group | Specific placements (X Profile, X Timeline, etc.) |
Tailored Audience | Ad Group | Tailored Audience targeting on the line item |
Interests | Ad Group | Interest targeting |
Keyword / Keyword Type | Ad Group | Keyword targeting and match type |
Location | Ad Group | Geo targeting |
Gender | Ad Group | Gender targeting |
Languages | Ad Group | Language targeting |
Age Bucket | Ad Group | Age range targeting |
Platforms | Ad Group | OS / platform targeting |
Devices | Ad Group | Device targeting |
App Store Categories | Ad Group | App-store category targeting |
Events | Ad Group | Event targeting |
Promoted Tweet ID | Ad | Promoted Tweet identifier |
Tweet ID | Ad | Underlying tweet identifier |
Tweet Status | Ad | Active or paused on the tweet |
Tweet Text | Ad | Full tweet copy (recommended over Promoted Tweet) |
Tweet URL | Ad | Direct URL to the tweet on x.com |
Card Name / Card ID | Ad | Twitter Card attached to the tweet |
Card Type | Ad | Card format (Website, App, Video, etc.) |
Images | Ad | Creative image used in the Card |
Video | Ad | Creative video used in the Card |
Creative Size | Ad | Pixel dimensions of the creative |
Creative Type | Ad | Image, video, carousel, etc. |
Metrics
Engagement & billing
Metric | Description |
TW: Impressions | Total impressions |
TW: Qualified Impressions | Impressions on tweets that loaded fully and were viewable |
TW: Engagements | Total engagements (clicks, retweets, replies, likes, follows, card engagements) |
TW: Billed Engagements | Engagements that were billed |
TW: Retweets | Total retweets |
TW: Replies | Total replies |
TW: Likes | Total likes |
TW: Follows | Follows attributed to the ad |
TW: Card Engagements | Engagements with the Twitter Card |
TW: Spend | Total spend (billed charge in account currency) |
Clicks
Metric | Description |
TW: Clicks | Total clicks |
TW: App Clicks | Clicks on app-install / app-open CTAs |
TW: Url Clicks | Clicks on links inside the tweet |
Video & media (currently in testing — may not work as expected)
Metric | Description |
TW: Total Video Views | All video views |
TW: Video Views — 25% / 50% / 75% / 100% | Quartile completion counts |
TW: Video Views — 3s, 100% | Views of at least 3 seconds and 100% in-view |
TW: Video MRC Views | MRC-qualified video views |
TW: Video CTA Clicks | Clicks on the video CTA |
TW: Video Playback Starts | Video playback starts |
TW: Media Views | Total media views |
TW: Media Engagements | Engagements with the media |
Derived rates & cost ratios
Metric | Description |
TW: Cost per 1k Impressions | CPM |
TW: Cost per 1k Qualified Impressions | CPM over qualified impressions only |
TW: Cost per Link Click | Spend / URL clicks |
TW: Cost per App Click | Spend / app clicks |
TW: Cost per Video View | Spend / video views (testing) |
TW: Cost per 3s/100% Video View | Spend / 3s 100% video views (testing) |
TW: Click Rate | Clicks / impressions |
TW: Link Click Rate | URL clicks / impressions |
TW: App Click Rate | App clicks / impressions |
TW: Media View Rate | Media views / impressions (testing) |
Web conversions
Web conversions are tracked via the X Pixel. Each event is reported as the metric below.
Metric | Description |
TW WC: Purchases | Web purchase events |
TW WC: Signups | Web signup events |
TW WC: Downloads | Web download events |
TW WC: Site Visits | Web site-visit events |
Mobile conversions
Mobile conversions are split by attribution window: Post View (the user saw the ad) and Post Engagement (the user clicked or otherwise engaged). Both variants are available for every event below.
Metric (Post View / Post Engagement) | Description |
TW MC: Installs | App installs |
TW MC: Spent Credits | In-app spend events |
TW MC: Content Views | Content-view events |
TW MC: Add To Wishlists | Wishlist add events |
TW MC: Add To Carts | Cart add events |
TW MC: Checkouts Initiated | Checkout-start events |
TW MC: Payment Info Additions | Payment-info entry events |
TW MC: Purchases | Mobile purchase events |
TW MC: Reservations | Reservation events |
TW MC: Tutorials Completed | Tutorial-completion events |
TW MC: Achievements Unlocked | Achievement-unlock events |
TW MC: Levels Achieved | Level-up events |
TW MC: Searches | In-app search events |
TW MC: Site Visits | In-app site-visit events |
TW MC: Key Page Views | Key-page-view events |
TW MC: Re Engages | Re-engagement events |
TW MC: Shares | In-app share events |
TW MC: Sign Ups | Mobile signup events |
TW MC: Logins | Login events |
TW MC: Updates | App-update events |
TW MC: Rates | Rating events |
TW MC: Downloads | Mobile download events |
TW MC: Invites | Invite events |
Conversion value
For purchase and other monetary events, the sale amount is also returned and converted from micro-currency to the account currency, then to your reporting currency. These appear as sale_amount_engagement / sale_amount_view on the Twitter conversions feed.
Limitations & known constraints
Backfill cap: a single backfill request can cover at most 30 days. Larger ranges are split into multiple runs.
Country segmentation: only Mobile Conversion metric groups support country segmentation; Engagement, Billing, Video, Media, and Web Conversions do not (per X's segmentation rules).
Placement merging: X exposes "All on Twitter" and "Publisher Network" stats via separate calls. Clarisights merges the two so you see one combined number per Promoted Tweet.
Truncated Promoted Tweet dimension: the older Promoted Tweet dimension carries the tweet copy and may be truncated; switch to Tweet Text for the full copy.
Beta video metrics: video and media-engagement metrics marked above as "in testing" may have inconsistent values.
Token revocation: revoking Clarisights' access from your X settings stops sync until you re-authorize from Integrations.
Operating notes
Refresh schedule: hourly. An incremental DAG covers the last 2 days; the main DAG covers the last 8 days for late-arriving data.
Lookback: 8 days on the regular schedule; backfill on connect goes back up to 30 days.
Currency conversion: spend and conversion values are returned by X in the account's native currency (with monetary fields delivered in micro-currency). Clarisights normalizes and converts them to your reporting currency.
Adding new ads accounts: when a new X Ads account is created on your X user, return to Integrations → Twitter and re-authorize or click Refresh accounts to pick it up.
Credential rotation: OAuth tokens persist until revoked. Refresh from Integrations → Twitter if the token becomes invalid (for example, after a password reset).
Need help?
When contacting support from the in-app messenger, please include:
The integration name and account ID (Integrations → Twitter)
The exact error message or screenshot
The step where the issue occurred
When the issue started