Tiktok Ads

---
name: tiktok-ads
description: Plan and create TikTok advertising campaigns end-to-end via the Hyper MCP, with strict parameter validation for objective-specific requirements. Use when the user wants to launch TikTok ads, set up TikTok traffic or reach campaigns, configure conversions or app-promotion campaigns, upload TikTok video creatives, or analyze TikTok ad performance. Also triggers on tiktok marketing, tiktok campaign, tiktok ppc, or tiktok ads manager.
requires_toolkits:
  - tiktok_marketing
icon: tiktok_ads
short_description: Plan and create TikTok Ads with objective-specific validation and reporting.
---

# TikTok Ads

Strategic guide for managing TikTok advertising campaigns. Research deeply, validate parameters carefully, and guide users through the platform's strict objective-specific requirements.

This skill is for **paid TikTok ads** (the TikTok Marketing API surface).

## Requirements

- **Hyper MCP installed and connected.** [https://app.hyperfx.ai/mcp](https://app.hyperfx.ai/mcp)
- **TikTok Marketing integration connected** (TikTok Ads Manager / Business Center) at [https://app.hyperfx.ai/apps](https://app.hyperfx.ai/apps).

If `search("tiktok_ads_advertiser_accounts_list")` does not find `tiktok_ads_advertiser_accounts_list`, stop and tell the user to enable Hyper MCP and connect TikTok Marketing.

### How to run the tools in this skill

Every tool in this skill is named by its canonical tool name. Run it with the call your surface gives you:

| Surface | Find a tool | Run it |
| --- | --- | --- |
| MCP client (Claude, Cursor, Codex, ChatGPT) | `search("<what you want to do>")`, then `describe("<name>")` | `call("<name>", {...})` |
| Hyper CLI | `hyperai search "<what you want to do>"`, then `hyperai describe <name>` | `hyperai call <name> --json '{...}'` |

If a tool is not found, its integration is not connected or not enabled for the workspace: stop and tell the user which integration to connect.

## Out of scope — defer to other skills

- **Organic TikTok posting** (videos, photos, carousels — no ad spend) → [`tiktok`](../tiktok).
- **Creative generation** (ad copy, images) → [`ad-creative-generation`](../ad-creative-generation); video creatives → [`video-generation`](../video-generation).
- **Cross-platform campaign launches** → use this skill for TikTok, then invoke `meta-ads` / `google-ads` separately.

## Tool surface

| Tool | Purpose |
| --- | --- |
| `tiktok_ads_advertiser_accounts_list` | Discovery: list advertiser IDs available to the connected user. |
| `tiktok_ads_campaigns_get`, `tiktok_ads_campaigns_create`, `tiktok_ads_campaigns_update`, `tiktok_ads_campaigns_status_update` | Campaign lifecycle. |
| `tiktok_ads_ad_groups_list`, `tiktok_ads_ad_groups_create`, `tiktok_ads_ad_groups_update`, `tiktok_ads_ad_groups_status_update` | Ad group lifecycle. |
| `tiktok_ads_list`, `tiktok_ads_create`, `tiktok_ads_ad_status_update`, `tiktok_ads_update` | Ad lifecycle and supported incremental content changes. Describe the selected tool before editing; Smart+ ads use their dedicated tools. |
| `tiktok_ads_videos_upload`, `tiktok_ads_videos_get`, `tiktok_ads_videos_search` | Video creative upload + lookup. |
| `tiktok_ads_integrated_reports_get` | Performance reporting. |
| `tiktok_ads_custom_audiences_create`, `tiktok_ads_custom_audiences_list`, `tiktok_ads_lookalike_audiences_create` | Audience management (optional). |

## Phase 1: Account Discovery

### Initial Setup
- Use `tiktok_ads_advertiser_accounts_list()` to get advertiser IDs.
- If multiple accounts: ask the user to select one.
- If single account: inform the user and proceed.

### Bid Benchmarks (optional but recommended)

Before setting bid prices, call `tiktok_ads_benchmarks_get` to retrieve industry-specific CPM/CPC benchmarks. This prevents using placeholder values that may be too low to win auctions or too high for the user's budget.

```python
tiktok_ads_benchmarks_get(
    advertiser_id="123456789",
    dimensions=["industry"],
    filtering={"industry": "292801"}  # industry code from tiktok_ads_advertiser_accounts_list
)
```

### Available Campaign Objectives

| Objective | Best For | Key Requirements |
| --- | --- | --- |
| `TRAFFIC` | Drive website visits | `promotion_type="WEBSITE"`, CPC billing |
| `CONVERSIONS` | Drive purchases / leads | Pixel ID, conversion event tracking |
| `REACH` | Brand awareness | Manual placement only, CPM billing, frequency cap |
| `APP_PROMOTION` | App installs | App ID, app store URL |
| `VIDEO_VIEW` | Video engagement | Video creative assets |

## Phase 2: Campaign Creation

### Step 1: Create Campaign

**Budget Requirements:**
- **MINIMUM $50** for campaign-level budgets (TikTok requirement).
- `budget_mode`: `BUDGET_MODE_INFINITE` (CBO), `BUDGET_MODE_DAY`, or `BUDGET_MODE_TOTAL`.

```python
tiktok_ads_campaigns_create(
    advertiser_id="123456789",
    campaign_name="Summer Sale 2026",
    objective_type="TRAFFIC",
    budget_mode="BUDGET_MODE_DAY",
    budget=50.0,  # MINIMUM $50/day
    operation_status="ENABLE"
)
```

### Step 2: Create Ad Group

**ALWAYS REQUIRED Parameters:**
- `advertiser_id`, `campaign_id`, `adgroup_name`.
- `location_ids` (e.g., `["6252001"]` for US).
- `schedule_type` and `schedule_start_time` (MUST be a future date).
- `billing_event` (`CPC`, `CPM`, `OCPM`).
- `budget_mode` (REQUIRED for ad groups).

**For TRAFFIC Campaigns:**
```python
tiktok_ads_ad_groups_create(
    advertiser_id="123456789",
    campaign_id="1234567890123456",
    adgroup_name="Website Traffic - Summer Sale",
    location_ids=["6252001"],  # US
    schedule_type="SCHEDULE_FROM_NOW",
    schedule_start_time="2026-06-01 00:00:00",  # FUTURE DATE
    billing_event="CPC",
    budget_mode="BUDGET_MODE_DAY",
    budget=30.0,
    promotion_type="WEBSITE",        # REQUIRED for TRAFFIC
    optimization_goal="CLICK",       # REQUIRED (correct spelling)
    bid_price=0.50,
    placement_type="PLACEMENT_TYPE_AUTOMATIC",
    operation_status="ENABLE"
)
```

**For REACH Campaigns:**
```python
tiktok_ads_ad_groups_create(
    advertiser_id="123456789",
    campaign_id="1234567890123456",
    adgroup_name="Brand Awareness US",
    location_ids=["6252001"],
    schedule_type="SCHEDULE_FROM_NOW",
    schedule_start_time="2026-06-01 00:00:00",
    billing_event="CPM",                       # REQUIRED for REACH
    budget_mode="BUDGET_MODE_DAY",
    budget=30.0,
    optimization_goal="REACH",
    placement_type="PLACEMENT_TYPE_NORMAL",    # REQUIRED — automatic NOT supported
    placements=["PLACEMENT_TIKTOK"],           # REQUIRED
    bid_price=2.0,                             # REQUIRED
    frequency=3,                               # REQUIRED
    frequency_schedule=7,                      # REQUIRED
    operation_status="ENABLE"
)
```

### Step 3: Upload Creative Assets

Upload one video per creative variant. Capture the returned `video_id` — you'll need it in Step 4.

```python
video_response = tiktok_ads_videos_upload(
    advertiser_id="123456789",
    video_file=video_data,
    upload_type="UPLOAD_BY_FILE"
)
video_id = video_response["data"]["video_id"]
```

> Already-uploaded videos can be reused. Use `tiktok_ads_videos_search` to find existing videos by name or `tiktok_ads_videos_get` to fetch metadata for a known video ID.

### Step 4: Create the Ad

```python
tiktok_ads_create(
    advertiser_id="123456789",
    adgroup_id="1234567890123456",
    ad_name="Summer Sale - Hero Video",
    identity_type="CUSTOMIZED_USER",   # or "AUTH_CODE" for TikTok Account spark ads
    identity_id="<advertiser_identity_id>",
    ad_format="SINGLE_VIDEO",
    video_id=video_id,
    ad_text="Limited-time summer drop. Shop now.",
    landing_page_url="https://example.com/summer",
    call_to_action="SHOP_NOW",
    operation_status="DISABLE"        # create paused, enable after review
)
```

Always create ads paused (`operation_status="DISABLE"`) and only flip them to `ENABLE` once the user has reviewed.

## Critical Parameter Rules

### Common Errors & Solutions

| Error | Solution |
| --- | --- |
| Budget must be at least $50 | TikTok enforces a MINIMUM $50 for campaign budgets. |
| Start time in past | Use a future date in `schedule_start_time` and the **current** year. |
| TikTok API rejects `optimize_goal` in some contexts | Both `optimize_goal` and `optimization_goal` exist in the schema, but prefer `optimization_goal` — it is the field TikTok validates in most objective types. |
| Only supports manual placement | REACH requires `placement_type="PLACEMENT_TYPE_NORMAL"`. |
| Bid needs to be greater than $0 | Set `bid_price` > 0. |
| Please set frequency cap | REACH requires both `frequency` and `frequency_schedule`. |

### Parameter Dependencies

**TRAFFIC objective requires:**
- `promotion_type="WEBSITE"`.
- `optimization_goal="CLICK"`.
- `billing_event="CPC"`.
- `bid_price` > 0.

**REACH objective requires:**
- `optimization_goal="REACH"`.
- `billing_event="CPM"`.
- `placement_type="PLACEMENT_TYPE_NORMAL"`.
- `placements` array (e.g., `["PLACEMENT_TIKTOK"]`).
- `bid_price` > 0.
- `frequency` and `frequency_schedule`.

**CONVERSIONS objective requires:**
- A connected TikTok Pixel and a configured conversion event.
- `optimization_goal="CONVERT"` (or `VALUE` for value-based).
- `billing_event="OCPM"`.
- `pixel_id` and `external_action` set on the ad group.

## Reporting

```python
tiktok_ads_integrated_reports_get(
    advertiser_id="123456789",
    report_type="BASIC",
    data_level="AUCTION_AD",
    dimensions=["ad_id"],   # ID-based only — NOT names
    start_date="2026-04-01",
    end_date="2026-04-30",
    metrics=["impressions", "clicks", "ctr", "spend", "cpc", "cpm"],
    page_size=20
)
```

**Reporting Rules:**
- With the `stat_time_day` dimension: maximum 30-day range per call.
- Use ID-based dimensions only (`ad_id`, `campaign_id`, `adgroup_id` — not names).
- Conversion metrics (`conversion`, `cost_per_conversion`, `conversion_rate`, etc.) require a connected pixel and a configured conversion event.
- `data_level` must match the dimension granularity: `AUCTION_AD` with `ad_id`, `AUCTION_ADGROUP` with `adgroup_id`, `AUCTION_CAMPAIGN` with `campaign_id`.

## Safety Rules

**Never:**
- Set ad group budgets below $20/day without warning the user.
- Schedule a campaign with a past `schedule_start_time` (TikTok rejects this with a confusing error).
- Mix REACH ad groups with `PLACEMENT_TYPE_AUTOMATIC` — it will silently fail validation.
- Create ads with `operation_status="ENABLE"` before the user has reviewed creative + targeting.
- Run reports with name-based dimensions — TikTok only accepts ID dimensions.