> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/ppc/twitter-ads.md).

# X (Twitter) Ads

Export X Ads campaign, ad group, and promoted tweet performance data to Google Sheets, BigQuery, or Airtable via Coupler.io — automated, no manual exports.

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

{% hint style="success" %}
Start with the **Campaign** entity to get a high-level view of spend and performance before drilling into ad groups or promoted tweets.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a new data flow** in Coupler.io and select **X (Twitter) Ads** as your source.
{% endstep %}

{% step %}
**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.
{% endstep %}

{% step %}
**Select your ad account.** Choose one or more ad accounts you want to pull data from.
{% endstep %}

{% step %}
**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.
{% endstep %}

{% step %}
**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.
{% endstep %}
{% endstepper %}

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

{% tabs %}
{% tab title="Paid social managers" %}

* Pull promoted tweet data daily to identify top-performing creatives and pause underperformers
* Use the keyword dimension on ad group reports to find high-spend, low-conversion terms
* Append X Ads campaign data with Meta or Google Ads using Coupler.io's Append transformation for a unified paid media dashboard
  {% endtab %}

{% tab title="Performance marketers" %}

* 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
  {% endtab %}

{% tab title="Reporting & analytics" %}

* 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
  {% endtab %}
  {% endtabs %}

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

<details>

<summary>OAuth authorization fails or loops back to the login screen</summary>

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.

</details>

<details>

<summary>Connected successfully but no ad accounts appear</summary>

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.

</details>

### Missing data

<details>

<summary>No data returned from the source</summary>

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.

</details>

<details>

<summary>Campaign name or tweet name is missing from the report</summary>

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.

</details>

<details>

<summary>Add-to-cart or purchase conversions show as zero or are missing</summary>

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.

</details>

### Permission errors

<details>

<summary>"Insufficient permissions" error when running the data flow</summary>

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.

</details>

### Data discrepancies

<details>

<summary>Metrics in Coupler.io don't match X Ads Manager</summary>

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.

</details>

### Rate limits

<details>

<summary>Data flow fails with a rate limit or API quota error</summary>

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.

</details>

## X (Twitter) Ads FAQ

<details>

<summary>Which X Ads entities should I use for a standard performance report?</summary>

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.

</details>

<details>

<summary>Why can't I see campaign or tweet names in my metrics report?</summary>

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.

</details>

<details>

<summary>Why are my add-to-cart or purchase conversions showing as zero?</summary>

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.

</details>

<details>

<summary>Can I pull data from multiple X Ads accounts into one report?</summary>

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.

</details>

<details>

<summary>What does the "Placement" parameter do and why do my totals look doubled?</summary>

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.

</details>

<details>

<summary>Can I send X Ads data to an AI tool for analysis?</summary>

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.

</details>

<details>

<summary>Why does my data flow return no data even though I have active campaigns?</summary>

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.

</details>

{% hint style="info" %}
For a full list of metrics included in each metric group, see the [Data Overview](#x-twitter-ads-data-overview) article. For help resolving connection or data problems, visit [Common Issues](#x-twitter-ads-common-issues). For setup recommendations, see [Best Practices](/sources/category/ppc/twitter-ads/best-practices.md).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/ppc/twitter-ads.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.