For the complete documentation index, see llms.txt. This page is also available as Markdown.

X (Twitter) Ads

X (Twitter) Ads is an advertising platform that lets you run promoted tweets, accounts, and campaigns across X. Connecting it to Coupler.io lets you pull your ad performance data automatically into any destination — no manual exports, no copy-pasting.

With Coupler.io, you can:

  • Export campaign, ad group, and promoted tweet performance data on a schedule

  • Combine X Ads data with other ad platforms (Google Ads, Meta Ads) using Append or Join transformations

  • Send data to Google Sheets, Excel, BigQuery, Looker Studio, or AI destinations like ChatGPT, Claude, or Gemini

  • Segment reports by device, location, gender, interest, keyword, and more

Prerequisites

  • An active X (Twitter) Ads account

  • Access to at least one ad account (you'll select it during setup)

  • A Coupler.io account (free trial available)

Quick start

How to connect

1

Create a new data flow in Coupler.io and select X (Twitter) Ads as your source.

2

Authorize via OAuth. Click "Connect" and sign in to your X account. Coupler.io will request read access to your X Ads data. Once authorized, your account will appear in the source settings.

3

Select your ad account. Choose one or more ad accounts you want to pull data from.

4

Choose an entity. Pick the report type you need — Campaign, Ad group, Promoted tweet, and so on. See the table below for what each entity contains.

5

Choose a destination. Connect Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like ChatGPT or Claude, then run the data flow manually to confirm everything is working.

X (Twitter) Ads data overview

X (Twitter) Ads gives you access to performance data across seven entities, from account-level summaries down to individual promoted tweets. You can segment nearly every report by demographics, geography, device, interest, and more.

Available entities

Entity
Best used for

Campaign

Budget pacing, overall ROAS, campaign comparison

Ad group (Line item)

Targeting analysis, bid strategy review

Promoted tweet

Creative performance, engagement rates

Promoted account

Follower acquisition tracking

Media creative

Visual ad performance

Funding instrument

Spend reconciliation, billing audit

Account

Cross-campaign rolled-up metrics

Metrics

Engagement metrics

Metric
Description

Impressions

Total number of times your ad was shown

Engagements

Total interactions (likes, retweets, replies, clicks)

Engagement rate

Engagements divided by impressions

Likes

Number of likes on promoted content

Retweets

Number of retweets

Replies

Number of replies

Follows

Followers gained from promoted account ads

Clicks

Total link clicks

URL clicks

Clicks specifically on the destination URL

Spend and billing metrics

Metric
Description

Spend

Total amount billed in your account currency

Billed charge

Charge amount per billing event

Billed engagements

Engagements that triggered a billing event

Video metrics

Metric
Description

Video views

Total video plays

Video completions

Number of times the video played to 100%

Video completion rate

Completions divided by views

3-second views

Views where at least 3 seconds were watched

6-second views

Views where at least 6 seconds were watched

Conversion metrics

Metric
Description

Conversions

Total tracked conversion events

Add to cart

Add-to-cart conversion events

Purchase

Purchase conversion events

Site visits

Website visit conversion events

App installs

App install conversion events

Dimensions

Segmentation dimensions

Dimension
Description

Age

Age brackets of users who saw or engaged with your ads

Gender

Gender breakdown

Devices

Device type (iOS, Android, desktop, mobile web)

Platform versions

OS version breakdown

Locations

Country-level geographic breakdown

Regions

Sub-national geographic breakdown

Cities

City-level breakdown (requires country selection)

Metros

Metro area breakdown (requires country selection)

Postal codes

Postal code breakdown (requires country selection)

Interests

Interest categories of your audience

Keywords

Keywords that triggered your ads

Audiences

Custom or tailored audience segments

Conversations

Conversation topics your audience engaged with

Languages

Language settings of users

Platforms

Platform types

Events

Live event targeting breakdown

TV shows

TV show conversation targeting

Similar to followers of user

Lookalike audience targeting

App store category

App categories for app-install campaigns

Time dimensions

Option
Description

Hour

Hourly granularity

Day

Daily granularity

Month

Monthly rollup

Common metric combinations

  • Campaign + Spend + Impressions + Clicks — standard performance dashboard

  • Promoted tweet + Engagements + Video views + URL clicks — creative effectiveness report

  • Ad group + Conversions + Add to cart + Spend — funnel analysis per ad group

  • Campaign + Device dimension — cross-device performance split

  • Account + Day granularity — daily spend pacing report

Use cases by role

  • Track add-to-cart and purchase conversions at the campaign and ad group level to calculate ROAS

  • Segment by device and platform version to spot drop-offs in mobile vs. desktop conversion paths

  • Use hourly granularity during campaign launches to monitor spend velocity

  • Join Campaign and Funding instrument entities to reconcile reported spend against billing records

  • Use Aggregate transformation to roll up ad group-level data into campaign summaries across multiple accounts

  • Send data to Looker Studio or BigQuery for cross-channel attribution reporting

Platform-specific notes

  • Each metric group contains a predefined set of metrics — you select groups, not individual metrics

  • The Placement parameter returns a separate row per placement type when set to "All"

  • Location-based dimensions (Cities, Metros, Postal codes, Regions) require you to select a country first

  • Device-based dimensions (Devices, Platform versions) require a platform selection (iOS, Android, etc.)

  • Conversion data relies on your X Pixel or conversion tags being correctly configured in your ad account

  • Historical data availability may vary depending on your X Ads account type and plan

X (Twitter) Ads common issues

Connection issues

OAuth authorization fails or loops back to the login screen

Make sure you're logged into the correct X account in your browser before starting the OAuth flow. If you manage multiple X accounts, log out of any personal accounts and log in with the account that has X Ads access. Then retry the connection in Coupler.io.

Connected successfully but no ad accounts appear

The X account you authorized must have access to at least one ad account. Check in X Ads Manager (ads.twitter.com) that your account is listed as an account user with at least read permissions. If you were recently added to an account, try disconnecting and reconnecting the source.

Missing data

No data returned from the source

First, confirm your date range overlaps with a period when the selected ad account had active campaigns. Check that your chosen entity (e.g., Promoted tweet) actually has data for that account — some entities may be empty if that campaign type was never used. Also verify that at least one metric group is selected.

Campaign name or tweet name is missing from the report

Name fields like campaign name or tweet name come from entity-level reports (Campaign, Promoted tweet), not from analytics reports. If you're pulling metrics only and don't see names, add a second source with the same entity set to pull metadata, then use Coupler.io's Join transformation to merge them on the campaign or tweet ID.

Add-to-cart or purchase conversions show as zero or are missing

Conversion metrics depend on your X Pixel and conversion tags being correctly set up in X Ads Manager. If the tags aren't firing, no conversion data will appear. Verify your tags are active under Tools > Conversion Tracking in X Ads Manager before pulling conversion metric groups.

Permission errors

"Insufficient permissions" error when running the data flow

The X account used for OAuth needs at least read access to the ad account. Campaign managers with restricted roles may not have API-level read access. Ask your X Ads account admin to verify your permission level under account user settings.

Data discrepancies

Metrics in Coupler.io don't match X Ads Manager

Check that your date range and granularity settings match what you're viewing in X Ads Manager. X Ads Manager uses your account's timezone — make sure your data flow date range accounts for this. Also confirm you're comparing the same placement type; selecting "All" returns a row per placement, which can cause totals to look inflated if you sum them.

Rate limits

Data flow fails with a rate limit or API quota error

X Ads API has rate limits that vary by account tier. If you're pulling large date ranges with hourly granularity and multiple segmentation dimensions simultaneously, you may hit these limits. Try reducing the date range, switching to daily granularity, or splitting your report into separate data flows for different entities.

X (Twitter) Ads FAQ

Which X Ads entities should I use for a standard performance report?

For most performance dashboards, start with Campaign for top-level metrics and Ad group (Line item) for targeting-level breakdowns. Add Promoted tweet if you want creative-level engagement data. Use Coupler.io's Join transformation to combine them on the campaign ID.

Why can't I see campaign or tweet names in my metrics report?

X Ads API returns entity names (like campaign name or tweet name) separately from performance metrics. Pull the Campaign or Promoted tweet entity to get names and IDs, then use Coupler.io's Join transformation to merge it with your analytics data on the shared ID field. This gives you named rows in your final report.

Why are my add-to-cart or purchase conversions showing as zero?

Conversion metrics are only populated if your X Pixel and conversion tags are correctly configured and firing in X Ads Manager. Go to Tools > Conversion Tracking in your X Ads account to confirm the tags are active. If they're not set up, the API will return zero for all conversion metrics regardless of your settings in Coupler.io.

Can I pull data from multiple X Ads accounts into one report?

Yes. Add a separate source for each ad account within the same data flow, then use the Append transformation to stack them into one table. It helps to add a custom column with the account name so you can filter or group by account in your destination.

What does the "Placement" parameter do and why do my totals look doubled?

When you set Placement to "All", X Ads API returns a separate row for each placement type (e.g., timelines, search, profiles). If you sum all rows, you'll get inflated totals. Either pick a specific placement to filter the report, or aggregate your data carefully in your destination after accounting for the placement breakdown.

Can I send X Ads data to an AI tool for analysis?

Yes. Coupler.io supports AI destinations including ChatGPT, Claude, Gemini, Cursor, Perplexity, and OpenClaw. You can route your X Ads data directly to these tools for natural-language analysis, campaign summaries, or automated reporting insights.

Why does my data flow return no data even though I have active campaigns?

Check three things: (1) your date range covers a period when the selected campaigns were running, (2) at least one metric group is selected, and (3) the entity you chose actually has data for that account (for example, Promoted account only returns data if you ran follower campaigns). See the Missing Data section in Common Issues for more detail.

For a full list of metrics included in each metric group, see the Data Overview article. For help resolving connection or data problems, visit Common Issues. For setup recommendations, see Best Practices.

Last updated

Was this helpful?