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

# TikTok

> What an agent can build in your TikTok ad account: objectives and goals, budgets and bidding, location ids and targeting, Spark Ads and other formats, and what it can't do.

Agents create TikTok campaigns, ad groups and ads in the advertiser account you selected
for TikTok in **Sources**. Everything starts disabled (paused). TikTok calls ad sets
**ad groups**: in every tool, an ad group goes where an ad set would.

## Before you start

| Requirement | Detail |
| - | - |
| TikTok connection | Connected in **Sources** after agent ads existed. It needs TikTok's ad account management, ads management and creative management permissions. An older connection shows `reconnect`: select **Reconnect**. |
| A TikTok account | Ads on TikTok placements run as a TikTok account (Spark Ads). `list_ad_identities` lists the accounts and custom identities this advertiser can use. |
| A TikTok pixel | Only for ad groups that optimize for website conversions |

## Campaigns

Pass `platform: "tiktok"` in `target`.

| Objective | The ad group optimizes for (`goal.optimize_for`) | Also needs |
| - | - | - |
| `sales` | `conversions` | A pixel and event. Event default `PURCHASE`. |
| `traffic` | `link_clicks` or `landing_page_views` | |
| `leads` | `conversions` on a website | A pixel and event. Event default `LEAD`. |
| `awareness` | `reach` | |
| `video_views` | `video_views` | TikTok placement |
| `engagement` | `followers` | TikTok placement |
| `app_promotion` | `app_installs` | The TikTok app id and `app_platform`: `android` or `ios` |

Pixel events: `PURCHASE`, `ADD_TO_CART`, `INITIATED_CHECKOUT`, `ADD_PAYMENT_INFO`, `LEAD`,
`COMPLETE_REGISTRATION`, `SUBSCRIBE`, `CONTACT`, `CONTENT_VIEW`, `SEARCH`. TikTok has no
web event for `START_TRIAL`.

## Budgets and bidding

| Where | Options |
| - | - |
| Campaign budget (Campaign Budget Optimization, shared by the ad groups) | `daily` for Sales, Traffic, Leads and App promotion campaigns, or `lifetime` for any objective |
| Ad group budget, when the campaign has none | `daily`, or `lifetime` with `end_time` at least one hour from now |
| Bidding | `lowest_cost` (TikTok's Maximum delivery, the default) or `cost_cap` with `amount`, the target cost per result |

Amounts are in the ad account's currency. `50` means 50.00. The preview warns when a
daily budget is below TikTok's minimum.

## Ad groups: targeting and placements

| Field | Values |
| - | - |
| `targeting.location_ids` | Required. TikTok location ids, not country codes. |
| `age_groups` | `AGE_18_24`, `AGE_25_34`, `AGE_35_44`, `AGE_45_54`, `AGE_55_100`. Leave out for 18+. |
| `genders` | `all` (default), `men` or `women` |
| `languages` | Language codes such as `en` |
| `interests` | Interest category ids |
| `custom_audiences`, `excluded_custom_audiences` | Audience ids from `list_ad_audiences` |
| `placements` | `automatic` (default), or a list of `tiktok`, `pangle` and `global_app_bundle` |
| `start_time`, `end_time` | `start_time` defaults to the preview's hour. TikTok refuses a start more than 12 hours in the past, so an old preview must be redone. |

### Find location ids

Ask the agent to look them up. It calls `search_targeting` with `platform: "tiktok"`,
`type: "location"`, the place name in `q`, and the campaign's `objective`. TikTok offers
different locations per objective, and the default is `traffic`. `type: "interest"` and
`type: "language"` work the same way.

```json theme={null}
{ "platform": "tiktok", "account_id": "7123456789012345678", "type": "location", "q": "Texas", "objective": "sales" }
```

## Ads

An agent adds up to 50 ads per call. TikTok allows 50 ads per ad group.

| Format | What it is | Files |
| - | - | - |
| `single_video` | A Spark Ad: TikTok posts your video as the TikTok account | One video, 9:16 (at least 540×960), 1:1 (640×640) or 16:9 (960×540), 1 second to 10 minutes. An optional cover in the video's shape. |
| `carousel` | Swipeable images with one music track | 1 to 35 images, 9:16, 1:1, 4:5 or 16:9, at most 1242×2340. Needs `platform_options.music_id`. |
| `single_image` | An image ad on Pangle or Global App Bundle | One image: 9:16 (720×1280), 1.91:1 (1200×628) or 1:1 (640×640) |
| `existing_post` | A Spark Ad that boosts a post already on the TikTok account | None. The post's caption is the ad text. |

| Ad rule | Detail |
| - | - |
| Ad text | 1 to 100 characters, no emoji. Chinese, Japanese and Korean characters count as 2. |
| Identity | A TikTok account from `list_ad_identities`. With one usable account, DATALYR fills it in. A custom identity runs only in ad groups on Pangle or Global App Bundle alone. |
| Call to action | Required, for example `SHOP_NOW`, `LEARN_MORE` or `SIGN_UP` |
| Link | Required, except in app promotion ad groups, where the ad links to the store page |
| `single_video` options | `dark_post` (default `true`) keeps the post off the account's profile. `allow_duet_stitch` defaults to `false`. The account must allow new videos to be posted for ads. |
| `carousel` placements | TikTok placement only, in Sales, Traffic, Leads, Awareness or App promotion campaigns. One link, text and call to action for the whole ad. |
| `existing_post` | The identity is the account the post is on, and it must share its posts with the ad account |

## What agents can't do on TikTok

| Not available | What happens |
| - | - |
| Smart+ and Upgraded Smart+ campaigns | Shown with `can_add_ads: false` |
| Smart Creative ad groups | Shown with `can_add_ads: false` |
| Special ad categories: housing, employment, credit | Shown with `can_add_ads: false` |
| Search Ads campaigns, catalog and shopping ad groups | Shown with `can_add_ads: false` |
| Sales campaigns that sell on TikTok Shop or in an app | Shown with `can_add_ads: false` |
| Ad groups that send people to an instant form, a chat, a call or a shop | Shown with `can_add_ads: false` |
| Ad groups that optimize for TikTok page visits | Shown with `can_add_ads: false` |
| Ads from a creator's authorization code | Refused |
| Archive, and new content for an existing ad | Refused. Pause or delete instead, and create a new ad. |

## Changes after launch

Turn on, pause, daily and lifetime budgets, and delete. See
[Change ads after launch](/agent-ads/change-ads). TikTok can spend up to 125% of a
campaign's daily budget on one day.

## Previews

TikTok returns its own preview link per ad in `previews`. There is no DATALYR
every-placement page for TikTok.

## Next

* [Add ad files](/agent-ads/files): videos and images for TikTok.
* [Turn ads on within spend limits](/agent-ads/live-ads-and-spend-limits): what turning on counts.
* [TikTok Ads](/integrations/tiktok-ads): connect TikTok and send conversions.


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