---
title: "Add an ad to a TikTok ad group (paused)"
method: POST
path: "/api/v1/tools/tiktok_add_ad/execute"
tags: ["TikTok Ads"]
---

# Add an ad to a TikTok ad group (paused)

`POST /api/v1/tools/tiktok_add_ad/execute`

## Request

- Base URL: `https://adako.ai`
- URL: `https://adako.ai/api/v1/tools/tiktok_add_ad/execute`
- Auth: HTTP bearer

Creates one more ad inside an existing TikTok ad group, PAUSED, from a video already in the library or an organic post (Spark Ad).
Use when: testing a second creative, or replacing one that tiktok_detect_creative_fatigue has flagged. Adding a fresh ad to a working ad group is the right way to handle fatigue: it keeps the ad group's learning, which pausing and rebuilding would throw away.
Do not upload a video here — this tool takes a video_id. Upload happens in tiktok_create_video_campaign, or the user uploads in Ads Manager and tiktok_list_ad_videos finds the id.
Do not add more than two or three ads to one ad group. TikTok concentrates delivery on whichever wins early, so extra ads mostly divide the learning rather than expand the test.
Do not guess the identity. TikTok requires one on every ad; list them with tiktok_list_identities and ask the user which account the ad appears as. A video_id ad also needs exactly one cover image (tiktok_upload_images).
Do not assume the new ad delivers immediately: it is created paused and, once resumed, TikTok reviews it first — usually a few hours.
Validates before creating: the identity (it must exist on the advertiser, be available, and be able to carry the post), the cover image, the ad text (no emoji; Chinese and Japanese characters count double), and the landing page the campaign's objective requires.
Returns the new ad id, read back from TikTok with its review status.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `arguments` object, required
    - `advertiser_id` string: TikTok advertiser id (a long numeric string). Only needed when the user has authorised more than one advertiser. Omit it to use the primary one.
    - `adgroup_id` string, required: The ad group to add the ad to, from tiktok_list_ad_groups.
    - `ad_name` string, required: Ad name, for the account's own reporting. No emoji.
    - `video_id` string: A video in the library, from tiktok_list_ad_videos.
    - `spark_item_id` string: An organic TikTok post id, for a Spark Ad from an existing post. Needs the posting account's identity and its permission.
    - `image_ids` string[]: The cover image, from tiktok_upload_images: exactly one id, same aspect ratio as the video. Required with video_id; not used with spark_item_id.
    - `ad_text` string, required: The caption shown with the video: up to 100 characters as TikTok counts them (Chinese and Japanese characters count as two), no emoji.
    - `call_to_action` 'LEARN_MORE' | 'SHOP_NOW' | 'SIGN_UP' | 'DOWNLOAD_NOW' | 'CONTACT_US' | 'APPLY_NOW' | 'BOOK_NOW' | 'GET_QUOTE' | 'SUBSCRIBE' | 'WATCH_NOW' | 'PLAY_GAME' | 'INSTALL_NOW' | 'READ_MORE' | 'VIEW_NOW' | 'ORDER_NOW', required: Button text on the ad.
    - `landing_page_url` string: Where the ad sends people; https only. Required for TRAFFIC and WEB_CONVERSIONS campaigns.
    - `identity_id` string: The identity the ad posts as, from tiktok_list_identities. TikTok requires one on every ad.
    - `identity_type` 'CUSTOMIZED_USER' | 'AUTH_CODE' | 'TT_USER' | 'BC_AUTH_TT': Identity kind, from tiktok_list_identities; read from TikTok when omitted. TikTok no longer accepts new ads as CUSTOMIZED_USER on placements that include TikTok.
    - `identity_authorized_bc_id` string: The Business Center a BC_AUTH_TT identity is authorised through, from tiktok_list_identities. Required for BC_AUTH_TT; read from TikTok when omitted.
    - `idempotency_key` string: Optional caller-supplied key; identical keys never execute twice.
    - `raw_data` boolean: Return compact JSON only (no markdown). Use when you will compute on the result.

## Response `200`

The tool ran. A write returns proposal_id and approve_url while the change waits for approval.

- SuccessEnvelope
  - `success` unknown, required
  - `tool` string, required
  - `data` object, required: Machine-readable result.
  - `markdown` string, required: The same result written for a person or a model.
  - `quota` Quota: Task usage for the current billing period.
    - `plan` string
    - `used` integer
    - `limit` integer
    - `period_end` string
    - `upgrade_url` string
  - `proposal_id` string: Present for writes. Nothing changes on the ad platform until it is approved.
  - `approve_url` string: Where a person approves the proposal.
  - `request_id` string, required

## Other responses

- `400`: Invalid arguments, or the ad account could not be resolved.
- `401`: Missing, invalid, revoked or expired API key.
- `402`: Monthly task quota used up, or the plan does not include this tool.
- `403`: The connected ad account lacks the access level this tool needs.
- `404`: Unknown tool name.
- `409`: Not connected, reconnect needed, confirmation required, a proposal already pending or no longer pending, an identical create that failed earlier today (proposal_failed_before), a create that duplicates an approved one (duplicate_create), the ad-account limit of the plan reached (account_limit), or an Idempotency-Key reused with different arguments.
- `429`: Rate limited by Adako or by the ad platform. See Retry-After.
- `500`: Unexpected error inside Adako.
- `502`: The ad platform returned an error.

---

[API](https://skmtc.dev/adako/apis/adako-rest-api.md) · [All operations](https://skmtc.dev/adako/apis/adako-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adako/apis/adako-rest-api/revisions/59ee60d48a56?raw)