> 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/tiktok-ads.md).

# TikTok Ads

Connect TikTok Ads to Coupler.io to automate campaign performance, ad metrics, and audience data exports on daily, weekly, or monthly schedules.

TikTok Ads is TikTok's advertising platform where you create and manage campaigns to promote your products or services. Connect your TikTok Ads account to Coupler.io to automate the export of campaign performance data, ad metrics, and audience insights on a schedule.

## Why connect to Coupler.io?

* **Automated reporting** — Pull TikTok Ads data on a daily, weekly, or monthly schedule without manual exports
* **Multi-account support** — Export data from multiple ad accounts in a single data flow
* **Flexible report types** — Choose from basic reports, audience insights, GMV Max, or Dynamic Showcase Ads data
* **Easy destination options** — Send data to Google Sheets, Excel, BigQuery, Looker Studio, or AI destinations like Claude and ChatGPT

## Prerequisites

* A TikTok Ads account with admin or operator access
* Permission to create API connections (check with your TikTok account administrator if you're unsure)
* A destination ready to receive data (Google Sheets, Excel, BigQuery, etc.)

## Quick start

{% hint style="success" %}
Start with a **basic campaign report** to see impressions, clicks, and spend across your campaigns. Once you've verified the data looks correct, you can add filters, dimensions, and metrics for more detailed analysis.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Sign in to Coupler.io** and create a new data flow. Select **TikTok Ads** as your source.
{% endstep %}

{% step %}
**Authorize your TikTok account** when prompted. A TikTok sign-in window will appear — enter your credentials and approve access. Coupler.io will request permission to read your ad account data.
{% endstep %}

{% step %}
**Select a report type** — choose from campaign, ad group, ad, or advertiser-level reports. If you're using GMV Max or Dynamic Showcase Ads, select the relevant report type.
{% endstep %}

{% step %}
**Choose your ad accounts** from the list. You can select multiple accounts to combine data in one export.
{% endstep %}

{% step %}
**Pick your destination** — Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like Claude or ChatGPT.
{% endstep %}

{% step %}
**Run the data flow manually** to test the connection and verify the data looks correct before scheduling.
{% endstep %}
{% endstepper %}

## Available report types

| Report Type                        | Data Level                    | Use Case                                                                     |
| ---------------------------------- | ----------------------------- | ---------------------------------------------------------------------------- |
| Basic campaign report              | Campaign                      | Track overall campaign performance (impressions, clicks, spend, conversions) |
| Basic ad group report              | Ad group                      | Analyze performance by ad set                                                |
| Basic ad report                    | Individual ad                 | Compare creative performance                                                 |
| Campaigns                          | Campaign structure            | Export static campaign list                                                  |
| Ads                                | Ad structure                  | Export static ad list                                                        |
| Basic advertiser report            | Account                       | Aggregate metrics across all campaigns                                       |
| Audience campaign report           | Campaign + audience breakdown | See performance by gender, age, country, interests                           |
| Audience ad report                 | Ad + audience breakdown       | Detailed audience insights at ad level                                       |
| Audience ad group report           | Ad group + audience breakdown | Audience breakdown by ad set                                                 |
| Audience advertiser report         | Account + audience breakdown  | Overall audience composition                                                 |
| GMV Max campaign report            | Campaign (commerce-focused)   | Track gross merchandise value for shopping campaigns                         |
| Dynamic Showcase Ads (DSA) reports | Campaign/ad/group/account     | Product-level performance for DSA campaigns                                  |
| Playable Ad reports                | By country                    | Performance of interactive playable ads                                      |

## TikTok Ads data overview

TikTok Ads reports give you visibility into campaign performance, audience engagement, and creative effectiveness. The data available depends on your report type and the dimensions/metrics you select.

## Report types

| Report                     | Granularity                           | Best for                                             |
| -------------------------- | ------------------------------------- | ---------------------------------------------------- |
| Basic campaign report      | Campaign level                        | Overall campaign health and ROI                      |
| Basic ad group report      | Ad group level                        | Testing ad set performance                           |
| Basic ad report            | Individual ad creative                | Creative testing and optimization                    |
| Audience breakdown reports | Campaign/ad/group + audience segments | Understanding who engages with your ads              |
| GMV Max                    | Campaign level (e-commerce)           | Tracking sales value and ROAS for shopping campaigns |
| Dynamic Showcase Ads (DSA) | Product level                         | Product-specific performance and attribution         |
| Playable Ads               | By country                            | Interactive ad engagement and geography              |

## Key metrics

#### Performance metrics

| Metric                   | Definition                               | Use                        |
| ------------------------ | ---------------------------------------- | -------------------------- |
| Impressions              | Number of times your ad was displayed    | Reach and visibility       |
| Clicks                   | Number of ad clicks                      | Engagement and traffic     |
| Click-through rate (CTR) | Clicks / impressions × 100               | Ad relevance and appeal    |
| Spend                    | Total ad spend in your selected currency | Budget tracking            |
| Cost per click (CPC)     | Spend / clicks                           | Efficiency metric          |
| Cost per mille (CPM)     | Spend / impressions × 1000               | Impression cost comparison |
| Conversions              | Number of completed conversion events    | Goal achievement           |
| Conversion rate          | Conversions / clicks × 100               | Landing page effectiveness |
| Cost per conversion      | Spend / conversions                      | Profitability per outcome  |

#### GMV Max metrics

| Metric                        | Definition                       |
| ----------------------------- | -------------------------------- |
| GMV (Gross Merchandise Value) | Total sales value driven by ads  |
| ROAS (Return on Ad Spend)     | Revenue / spend                  |
| Orders                        | Number of completed transactions |

#### Engagement metrics

| Metric                  | Definition                            |
| ----------------------- | ------------------------------------- |
| Video plays             | Number of times your video was played |
| Video 100% plays        | Fully completed views                 |
| Likes, comments, shares | Direct audience interaction on TikTok |

## Dimensions (breakdowns)

#### Standard dimensions

| Dimension       | Available in          | Use                               |
| --------------- | --------------------- | --------------------------------- |
| Campaign name   | All reports           | Group data by campaign            |
| Ad group name   | Ad group & ad reports | Compare ad set performance        |
| Ad name         | Ad report             | Identify top-performing creatives |
| Advertiser name | Advertiser reports    | Multi-account analysis            |

#### Audience dimensions

| Dimension         | Available in             | Use                               |
| ----------------- | ------------------------ | --------------------------------- |
| Gender            | Audience reports         | Gender-based performance          |
| Age               | Audience reports         | Age group targeting effectiveness |
| Country code      | Audience & basic reports | Geographic performance            |
| Language          | Audience reports         | Language-based engagement         |
| Platform          | Audience reports         | Device/platform performance       |
| Interest category | Audience reports         | Interest-based audience insights  |
| Placement         | Audience reports         | In-feed vs. other placements      |
| Contextual tag    | Audience reports         | Content context performance       |

#### Asset dimensions

| Dimension         | Available in  | Use                              |
| ----------------- | ------------- | -------------------------------- |
| Video material ID | Basic reports | Video-level performance tracking |
| Image ID          | Basic reports | Image asset performance          |
| Page ID           | Basic reports | Landing page performance         |
| Post ID           | Basic reports | Post-based campaign tracking     |
| Component name    | Basic reports | Ad component breakdown           |

#### DSA dimensions

| Dimension      | Available in | Use                            |
| -------------- | ------------ | ------------------------------ |
| Catalog ID     | DSA reports  | Multi-catalog performance      |
| Product set ID | DSA reports  | Product collection performance |
| Product ID     | DSA reports  | Individual product tracking    |
| SKU ID         | DSA reports  | SKU-level sales tracking       |

## Common metric combinations

**Campaign Performance Overview:** Impressions, clicks, spend, conversions, conversion rate

**Creative Testing:** Impressions, CTR, cost per conversion (grouped by ad)

**Audience Insights:** Impressions, spend, conversions by gender, age, country

**Geo Performance:** Spend, conversion rate, ROAS by country code

**Product Performance (DSA):** Impressions, clicks, GMV, ROAS by product ID

## Use cases by role

{% tabs %}
{% tab title="Performance Marketers" %}
Track campaign efficiency metrics (CPC, CPM, ROAS) and optimize bid strategies. Use basic campaign/ad reports with metrics like spend, conversions, and conversion rate. Group by campaign or ad to identify underperforming creatives and reallocate budget.
{% endtab %}

{% tab title="E-commerce Managers" %}
Use GMV Max reports to tie ad spend directly to sales value and calculate ROAS. Break down performance by product ID (DSA) or campaign to understand which products drive the most revenue. Monitor conversion rate and cost per conversion by product.
{% endtab %}

{% tab title="Analytics & BI Teams" %}
Build multi-account dashboards in Looker Studio or BigQuery. Combine TikTok Ads data with other sources (Meta Ads, Google Ads) using Coupler.io's Append transformation. Create audience segment analysis reports by geography, interest, and platform.
{% endtab %}

{% tab title="Audience Strategists" %}
Use audience breakdown reports to understand which demographics and interests convert best. Segment performance by gender, age, interest category, and language. Export to a tool like Claude or ChatGPT to generate audience insights and recommendations.
{% endtab %}
{% endtabs %}

## Platform-specific notes

* **Data freshness:** TikTok Ads data is typically updated within 24 hours. Schedule refreshes for early morning to access yesterday's complete data.
* **Time zones:** All metrics are reported in your TikTok Ads account time zone. Verify your account settings in TikTok Ads Manager.
* **Attribution window:** TikTok uses a 1-day click attribution window by default. Conversions are attributed to the ad click date, not the conversion date.
* **Multi-account exports:** When selecting multiple ad accounts, data is combined in a single export. Use the advertiser name dimension to distinguish accounts.
* **GMV Max requirement:** GMV Max reports are only available if you have GMV Max campaigns active and linked to a TikTok Shop or e-commerce catalog.
* **API limits:** TikTok enforces rate limits on API requests. If you see "API failed" errors, wait 15–30 minutes before retrying.

## TikTok Ads common issues

### Connection issues

<details>

<summary>Sign-in popup doesn't appear or is blocked</summary>

Your browser may be blocking popups from TikTok. Check your browser's popup blocker settings and allow popups for `accounts.tiktok.com`. Alternatively, try a different browser or incognito/private window.

</details>

<details>

<summary>"Invalid credentials" or "Authorization failed" error</summary>

Your TikTok account credentials are correct, but Coupler.io doesn't have permission to access your ad account. Verify:

1. You signed in with the correct TikTok account (the one that owns your ad accounts)
2. Your account has admin or operator role in TikTok Ads Manager
3. Two-factor authentication (2FA) is not preventing the connection

If you're still blocked, disconnect and reconnect your TikTok account in the ['Connections'](https://www.coupler.io/app/connections) section.

</details>

<details>

<summary>"Missing permissions or access rights" error</summary>

Your TikTok account doesn't have the required permissions to create API connections. Contact your TikTok account administrator and request:

* **Admin** or **Operator** role in TikTok Ads Manager
* Permission to access the **Ads Manager API**

Once permissions are granted, disconnect and reconnect your TikTok account.

</details>

### Missing data

<details>

<summary>No data appears after connecting my TikTok account</summary>

Check these common reasons:

1. **Empty ad account:** Your selected ad account may have no campaigns, ads, or data in the selected date range. Verify campaigns are active in TikTok Ads Manager.
2. **Wrong ad account selected:** You may have selected a different account than the one with active campaigns. Verify the advertiser name matches your expected account.
3. **Date range:** If you selected "Campaigns" or "Ads" report type (snapshot reports), the date range is ignored. These reports show current structure only, not historical data.
4. **Filters applied:** If you've set advanced filters, they may be excluding all data. Try removing filters or loosening criteria.

Run the data flow again and check the logs for API error messages.

</details>

<details>

<summary>Expected metrics or dimensions don't appear in the export</summary>

Some metrics are only available in specific report types or when certain dimensions are selected:

* **Conversion metrics** (conversions, conversion rate, cost per conversion) require an active conversion tracking pixel or app event in TikTok Ads.
* **Audience breakdown metrics** are only available in "Audience" report types.
* **GMV metrics** (revenue, ROAS, orders) are only available in "GMV Max campaign report."
* **Product data** (product ID, SKU) is only available in Dynamic Showcase Ads (DSA) reports.

Select the correct report type and metrics for your analysis.

</details>

<details>

<summary>Data is different from TikTok Ads Manager</summary>

Small discrepancies are normal due to timing and attribution differences:

* **Data freshness:** API data may lag the dashboard by 24 hours. Export yesterday's data, not today's.
* **Attribution window:** The API uses a 1-day click attribution window. TikTok Ads Manager may use different windows (1, 3, 7, or 30 days).
* **Time zone:** Verify your TikTok Ads Manager account time zone matches your export time zone.
* **Filters:** Advanced filters in Coupler.io may exclude data that appears in the full dashboard.

If discrepancies persist, contact TikTok support for clarification on API attribution rules.

</details>

### Permission errors

<details>

<summary>"Access denied" when pulling advertiser/account data</summary>

Your TikTok account role doesn't have access to all selected ad accounts. Verify in TikTok Ads Manager that your account has admin or operator access to each advertiser you're trying to export from. If you don't see certain accounts in Coupler.io's advertiser list, those accounts may not be accessible to your role.

</details>

### Data discrepancies

<details>

<summary>Campaign data seems duplicated or has inconsistent row counts</summary>

This can occur if:

1. **Dimensions are creating extra rows:** If you selected multiple dimensions (e.g., country code AND age), each combination creates a separate row. Verify your dimension selections in the data flow settings.
2. **Time period split:** If you selected "Split data by period" (hourly, daily, etc.), each time bucket is a separate row. Check your "Split data by period" setting.
3. **Append with duplicate data:** If you've appended data from multiple data flows, ensure you're not pulling the same date range twice.

Review your report configuration in Coupler.io and adjust dimensions or time splits as needed.

</details>

<details>

<summary>Conversion counts don't match between Coupler.io and TikTok Ads Manager</summary>

TikTok's API and dashboard may use different attribution models:

* **API:** 1-day click attribution window
* **Dashboard:** Customizable window (1, 3, 7, or 30 days)

Small variations are normal. If you need to match the dashboard exactly, check the attribution window setting in TikTok Ads Manager and compare it to your export date range.

</details>

### Rate limits

<details>

<summary>"Request to TikTok API has failed" error</summary>

TikTok enforces API rate limits to prevent abuse. If you see this error:

1. **Wait 15–30 minutes** before retrying the data flow
2. **Reduce date range:** Pulling very large date ranges (e.g., 1+ years) can trigger rate limits. Try exporting 3–6 months at a time.
3. **Decrease frequency:** If you're running multiple data flows simultaneously, space them out (e.g., 10–15 minutes apart) to avoid hitting limits.
4. **Simplify report:** Removing unnecessary dimensions or metrics can reduce API query complexity.

If errors persist after waiting, contact Coupler.io support with your data flow ID.

</details>

<details>

<summary>Data flow has been disabled due to repeated API failures</summary>

If Coupler.io detects multiple consecutive API failures, it automatically disables the data flow to prevent wasted resources. Common causes:

* TikTok API outage or maintenance
* Rate limit exceeded (see above)
* Your TikTok account permissions were revoked or changed
* Selected ad account no longer exists

Check TikTok's API status page, wait 1 hour, then re-enable the data flow in Coupler.io. If the issue continues, reconnect your TikTok account.

</details>

## TikTok Ads FAQ

<details>

<summary>Can I export data from multiple TikTok Ads accounts in one data flow?</summary>

Yes. When you select your ad accounts, you can choose multiple accounts from the dropdown. All data will be combined in a single export. Include the "Advertiser name" dimension so you can distinguish which rows belong to which account. If you need to aggregate metrics across accounts, use Coupler.io's Aggregate transformation.

</details>

<details>

<summary>What's the difference between "Campaigns" and "Basic campaign report"?</summary>

"Campaigns" is a snapshot report showing your current campaign structure (name, status, budget, bid strategy) without performance metrics or a specific date range. "Basic campaign report" shows performance metrics (impressions, clicks, spend, conversions) for a selected date range. Use "Campaigns" if you need a list of active campaigns; use "Basic campaign report" for performance analysis.

</details>

<details>

<summary>Can I break down data by multiple dimensions at once (e.g., country AND age)?</summary>

Yes. In the "Audience dimensions" or other dimension fields, you can select multiple options. Each combination will create a separate row in your export. For example, if you select "Country code" and "Age," you'll see impressions/clicks/spend for each country-age combination. Note: this increases the number of rows and API query size, so results may take longer.

</details>

<details>

<summary>Why is my conversion data missing or zero?</summary>

Conversion data requires an active conversion tracking pixel or app event in your TikTok Ads account. If you don't see conversions in your export:

1. Go to TikTok Ads Manager → Conversions
2. Verify you have at least one active pixel or app event
3. Check that your campaigns are configured to track that conversion
4. Wait 24 hours for data to populate (new pixels take time)

Once verified, re-run your Coupler.io data flow.

</details>

<details>

<summary>Can I use date macros to automate my date range?</summary>

Yes. TikTok report types that support date ranges (e.g., "Basic campaign report") allow date macros. Instead of manually entering dates, use macros like `{{previousMonth}}`, `{{30daysago}}`, or `{{startOfMonth}}`. This way, your data flow automatically pulls rolling date ranges without manual updates. See [Coupler.io's macro documentation](https://docs.coupler.io/functionality/macros-in-data-flows) for the full list.

</details>

<details>

<summary>What's the difference between audience reports and basic reports?</summary>

Basic reports (campaign, ad group, ad) show performance metrics aggregated by your campaign structure. Audience reports show the same metrics broken down by audience segments (gender, age, country, interests, language, platform, etc.). Use basic reports for quick performance overviews; use audience reports when you want to understand which demographic or interest segment converts best.

</details>

<details>

<summary>How often should I refresh my data flow?</summary>

TikTok's API updates data within 24 hours. Schedule daily refreshes for early morning (6–8 AM) so you're pulling yesterday's complete data. Avoid hourly or 4-hour schedules; they'll hit rate limits and waste resources. If you only need weekly reports, schedule once per week (e.g., Monday morning).

</details>

<details>

<summary>Can I combine TikTok Ads data with other ad platforms (Meta, Google Ads)?</summary>

Yes. Create separate data flows for each platform, then use Coupler.io's **Append** transformation to combine them in one spreadsheet or table. For example, append TikTok campaign data with Meta campaign data, then use a pivot table to compare performance across platforms. You can also use **Join** if you want to match campaigns by name or date.

</details>

<details>

<summary>What should I do if I see "Request to TikTok API has failed"?</summary>

This is usually temporary. Wait 15–30 minutes, then try running the data flow again. If it persists:

1. Reduce your date range (large ranges can timeout)
2. Remove unnecessary dimensions or metrics
3. Check that your selected ad accounts still exist in TikTok Ads Manager
4. Reconnect your TikTok account in Coupler.io's Connections section

If errors continue, contact Coupler.io support with your data flow ID.

</details>

<details>

<summary>Can I send TikTok Ads data to ChatGPT or Claude?</summary>

Yes. Coupler.io supports AI destinations including ChatGPT, Claude, Cursor, Gemini, Perplexity, and OpenClaw. Select your AI destination instead of a traditional spreadsheet or data warehouse. This is useful for generating insights, creating summaries, or automating analysis — for example, "Summarize my top 5 performing campaigns and suggest bid adjustments."

</details>

<details>

<summary>Why does my data look different from TikTok Ads Manager?</summary>

Small differences are normal and usually due to:

* **Data freshness:** The API lags by up to 24 hours; the dashboard shows real-time estimates
* **Attribution window:** The API uses 1-day click attribution; the dashboard may use 3, 7, or 30 days
* **Time zone:** Verify your TikTok Ads Manager and export time zones match
* **Filters:** Coupler.io filters may exclude data visible in the dashboard

{% hint style="info" %}
For details on available metrics and how attribution works, see the [Data Overview](#tiktok-ads-data-overview).
{% endhint %}

</details>

<details>

<summary>Can I pull data for GMV Max or Dynamic Showcase Ads campaigns?</summary>

Yes. Select "GMV Max campaign report" for GMV Max campaigns or any of the "Dynamic Showcase Ads (DSA)" report types for DSA campaigns. These reports include product-level data (product ID, SKU, catalog) and commerce-specific metrics (GMV, revenue, orders, ROAS). You must have active GMV Max or DSA campaigns and a linked e-commerce catalog or TikTok Shop to use these reports.

</details>

<details>

<summary>How do I handle duplicate data if I pull the same date range twice?</summary>

If you've accidentally pulled overlapping dates and your destination is in Append mode, you'll have duplicates. Use Coupler.io's **Deduplicate** transformation to remove them. Alternatively, delete the duplicate rows manually in your spreadsheet. In the future, use date macros or carefully track which date ranges you've already exported.

</details>


---

# 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/tiktok-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.
