> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TikTok Ads

> Connect your TikTok advertiser account, create and manage campaigns, ad groups and ads, upload creatives, and read performance.

**TikTok Ads** connects your own TikTok advertiser account to Appeeky. Once connected, you or your AI assistant can create campaigns, ad groups and ads (including Automated Creative Optimization ads), upload images and videos, turn delivery on and off, and read spend, installs and cost per install.

> [!NOTE]
>
> Requires a signed-in Appeeky account on the **Indie plan or higher** and a connected TikTok advertiser account.

***

## How it works

```
Connect TikTok  →  default advertiser  →  campaign  →  ad group  →  upload media  →  ad  →  enable  →  performance
```

* **Default advertiser.** Every endpoint accepts `advertiserId`. Leave it out and Appeeky uses your default advertiser. After you connect, the first advertiser on your login becomes the default; change it any time.
* **TikTok fields as-is.** Create and update requests take TikTok Marketing API fields in snake\_case (`campaign_name`, `objective_type`, `budget_mode`, ...). Appeeky fills in `advertiser_id` and checks the required fields before sending.
* **Budgets** are in your advertiser account's currency.

***

## Connect TikTok Ads

In the dashboard: **Settings → Data sources → Ads**, then connect TikTok Ads and sign in with TikTok.

| Method | Endpoint | Description |
| - | - | - |
| GET | `/v1/connect/tiktok-ads/oauth/start` | Returns `authorizeUrl` to open in a browser (`?return_to=` optional) |
| GET | `/v1/connect/tiktok-ads/credentials/status` | Connection status and default advertiser |
| GET | `/v1/connect/tiktok-ads/advertisers` | Advertisers your TikTok login can manage, with currency and time zone |
| GET | `/v1/connect/tiktok-ads/advertisers/stored` | Advertisers saved on your Appeeky account |
| PATCH | `/v1/connect/tiktok-ads/advertisers/:advertiserId/default` | Set the default advertiser |
| DELETE | `/v1/connect/tiktok-ads/credentials` | Disconnect TikTok Ads |

If you create a new advertiser in TikTok after connecting, call `GET /v1/connect/tiktok-ads/advertisers` to pick it up. You don't need to reconnect.

***

## Campaigns, ad groups and ads

| Method | Endpoint | Description |
| - | - | - |
| GET | `/v1/connect/tiktok-ads/campaigns` | List campaigns |
| POST | `/v1/connect/tiktok-ads/campaigns` | Create a campaign |
| PATCH | `/v1/connect/tiktok-ads/campaigns/:campaignId` | Update campaign fields |
| POST | `/v1/connect/tiktok-ads/campaigns/:campaignId/status` | Enable or disable |
| GET | `/v1/connect/tiktok-ads/adgroups` | List ad groups (`?campaignId=` optional) |
| POST | `/v1/connect/tiktok-ads/adgroups` | Create an ad group |
| PATCH | `/v1/connect/tiktok-ads/adgroups/:adgroupId` | Update ad group fields |
| POST | `/v1/connect/tiktok-ads/adgroups/:adgroupId/status` | Enable or disable |
| GET | `/v1/connect/tiktok-ads/ads` | List ads (`?campaignId=`, `?adgroupId=` optional) |
| GET | `/v1/connect/tiktok-ads/adgroups/:adgroupId/ads` | List ads in one ad group |
| POST | `/v1/connect/tiktok-ads/ads` | Create manual ads |
| PATCH | `/v1/connect/tiktok-ads/ads/:adId` | Update a manual ad |
| POST | `/v1/connect/tiktok-ads/ads/:adId/status` | Enable or disable |
| POST | `/v1/connect/tiktok-ads/aco-ads` | Create a smart creative (ACO) ad |
| PATCH | `/v1/connect/tiktok-ads/aco-ads/:adId` | Update a smart creative ad |

List endpoints paginate with `?page=` (default 1) and `?pageSize=` (default 100, max 1000). Campaign list and create also work under `/v1/connect/tiktok-ads/advertisers/:advertiserId/campaigns`.

### Create a campaign

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/connect/tiktok-ads/campaigns
{
  "advertiserId": "7000000000000000000",
  "campaign_name": "Dibble - US installs",
  "objective_type": "APP_PROMOTION"
}
```

`campaign_name` and `objective_type` are required. Any other TikTok campaign field is passed through.

### Create an ad group

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/connect/tiktok-ads/adgroups
{
  "campaign_id": "1800000000000000000",
  "adgroup_name": "US - broad",
  "budget_mode": "BUDGET_MODE_TOTAL",
  "budget": 50,
  "billing_event": "OCPM",
  "optimization_goal": "INSTALL",
  "pacing": "PACING_MODE_SMOOTH",
  "schedule_type": "SCHEDULE_START_END",
  "schedule_start_time": "2026-11-03 12:00:00",
  "schedule_end_time": "2026-11-17 12:00:00"
}
```

Required: `campaign_id`, `adgroup_name`, `budget_mode`, `budget`, `billing_event`, `optimization_goal`, `pacing`, `schedule_start_time` and `schedule_type`. Add targeting (such as `location_ids`), placements and app fields the same way, as your campaign type requires.

### Create an ad

* **Manual ad** — `adgroup_id` and a non-empty `creatives` array in TikTok's ad format. Use the image or video ids from [media upload](#upload-images-and-videos) and an identity from [identities](#identities).
* **Smart creative (ACO) ad** — `adgroup_id` plus TikTok's ACO fields (for example `media_info_list`, `title_list`, `common_material`). TikTok builds the ads from the assets and copy you provide.

### Enable or disable

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/connect/tiktok-ads/campaigns/1800000000000000000/status
{ "operationStatus": "DISABLE" }
```

`operationStatus` is `ENABLE` or `DISABLE`. To change several at once, send `campaignIds`, `adgroupIds` or `adIds` as an array in the body.

***

## Identities

The identity is the name and avatar your ad shows.

| Method | Endpoint | Description |
| - | - | - |
| GET | `/v1/connect/tiktok-ads/identities` | List identities (`?identity_type=`, `?identity_authorized_bc_id=` optional; `?pageSize=` max 100) |
| POST | `/v1/connect/tiktok-ads/identities` | Create a custom identity (`display_name` and `image_uri` required) |

***

## Upload images and videos

Upload media from a public URL. The response includes the asset ids to use in your ads.

| Method | Endpoint | Description |
| - | - | - |
| POST | `/v1/connect/tiktok-ads/assets/images/from-url` | Upload an image (`imageUrl`, optional `fileName`) |
| POST | `/v1/connect/tiktok-ads/assets/videos/from-url` | Upload a video (`videoUrl`, optional `fileName`) |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/connect/tiktok-ads/assets/videos/from-url
{
  "videoUrl": "https://example.com/ugc-hook-01.mp4",
  "fileName": "ugc-hook-01"
}
```

***

## Performance

`GET /v1/connect/tiktok-ads/performance` returns spend, impressions, clicks, installs (conversions), cost per install, CPC, CTR and conversion rate, with a row per campaign, ad group or ad and totals. Rows are sorted by spend.

| Query | Notes |
| - | - |
| `level` | `advertiser`, `campaign` (default), `adgroup` or `ad` |
| `days` | Relative window, 1–730 days. Default 14 |
| `from` / `to` | `YYYY-MM-DD`. Override `days` |
| `limit` | Max rows, 1–1000. Default 200 |
| `currency` | Display currency label, e.g. `USD` (default) |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.appeeky.com/v1/connect/tiktok-ads/performance?level=campaign&days=7" \
  -H "X-API-Key: $APPEEKY_API_KEY"
```

For a raw TikTok report with your own dimensions and metrics, use `GET /v1/connect/tiktok-ads/report` with `dataLevel` (`AUCTION_ADVERTISER`, `AUCTION_CAMPAIGN` default, `AUCTION_ADGROUP`, `AUCTION_AD`), `dimensions`, `metrics`, `startDate` and `endDate`.

***

## MCP tools

| Tool | Description |
| - | - |
| `tiktok_ads_oauth_start` | Get the TikTok connect link |
| `tiktok_ads_credentials_status` | Check whether TikTok Ads is connected |
| `tiktok_ads_list_advertisers` | List advertisers |
| `tiktok_ads_set_default_advertiser` | Set the default advertiser |
| `tiktok_ads_list_campaigns` / `tiktok_ads_create_campaign` | List or create campaigns |
| `tiktok_ads_update_campaign` / `tiktok_ads_update_campaign_status` | Update or enable/disable a campaign |
| `tiktok_ads_list_adgroups` / `tiktok_ads_create_adgroup` | List or create ad groups |
| `tiktok_ads_update_adgroup` / `tiktok_ads_update_adgroup_status` | Update or enable/disable an ad group |
| `tiktok_ads_list_ads` / `tiktok_ads_create_ad` | List or create manual ads |
| `tiktok_ads_update_ad` / `tiktok_ads_update_ad_status` | Update or enable/disable an ad |
| `tiktok_ads_create_aco_ad` / `tiktok_ads_update_aco_ad` | Create or update smart creative ads |
| `tiktok_ads_list_identities` | List identities |
| `tiktok_ads_upload_image_from_url` | Upload an image |
| `tiktok_ads_upload_video_from_url` | Upload a video |
| `tiktok_ads_performance` | Spend, installs and cost per install |

***

## Credits

| Request | Cost |
| - | - |
| Connect, status, advertiser list and default | Free |
| Other `/connect/tiktok-ads` reads and writes | 2 credits per request |

Requests made from the Appeeky dashboard don't use API credits. Ad spend is billed by TikTok to your advertiser account.

***

## Common errors

| Code | Meaning |
| - | - |
| `PRO_FEATURE` | Ads integrations need the Indie plan or higher |
| `TIKTOK_ADS_CONNECTION_REQUIRED` | Connect TikTok Ads first |
| `TIKTOK_ADVERTISER_REQUIRED` | Pass `advertiserId` or set a default advertiser |
| `TIKTOK_MISSING_FIELD` | A required TikTok field is missing; the message names it |
| `TIKTOK_STATUS_UPDATE_INVALID` | `operationStatus` must be `ENABLE` or `DISABLE` |

***

## Related

* [Meta Ads](https://docs.appeeky.com/docs/meta-ads.md) — Facebook and Instagram campaigns
* [Apple Search Ads](https://docs.appeeky.com/docs/apple-search-ads.md) — App Store search campaigns


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.