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

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

`POST /api/v1/tools/tiktok_add_ad_group/execute`

## Request

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

Creates one more ad group inside an existing TikTok campaign, PAUSED, with its own budget, schedule and targeting.
Use when: the user wants to test a second audience, split budget across markets, or add a market to a campaign that already works. The campaign's objective decides what the ad group may optimise for, so nothing has to be chosen twice.
Do not use it to change an existing ad group — that is tiktok_update_ad_group. Do not create near-duplicate ad groups targeting overlapping audiences: on TikTok they bid against each other and both get more expensive.
Do not add an ad group and expect it to deliver: it is created paused and it has no ads. Add one with tiktok_add_ad, then resume both.
Validates before creating: the optimisation goal against the campaign's objective, the ad group budget range for the account's currency, the bid against its limits and both budgets, the schedule (the advertiser's days; a past start is refused), the pixel and event when the objective needs them (the pixel must be on the account and receive that event), every location id and language code against TikTok's lists (overlapping locations and the under-18 rules included), and the campaign's special ad category limits.
Returns the new ad group id, read back from TikTok.

## 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.
    - `campaign_id` string, required: The campaign to add the ad group to, from tiktok_list_campaigns.
    - `adgroup_name` string, required: Ad group name. No emoji.
    - `daily_budget` number, required: Daily budget, decimal in the account currency.
    - `optimization_goal` string: What to optimise for. Omit to take the campaign objective's default; tiktok_explain_objective lists the valid pairs.
    - `pixel_id` string: Pixel to optimise against, for conversion objectives. From tiktok_list_pixels.
    - `optimization_event` string: The pixel event to optimise for, e.g. ON_WEB_ORDER.
    - `bid` number: Manual bid (cost cap), decimal in the account currency. The unit follows the optimisation goal: per click for CLICK and PAGE_VISIT, per 1,000 impressions for REACH, per focused view for ENGAGED_VIEW and ENGAGED_VIEW_FIFTEEN, and a target cost per result for FOLLOWERS, CONVERT and VALUE. It must be lower than both the ad group and the campaign budget. Omit to let TikTok bid automatically, which is the right default for a new ad group.
    - `start_date` string: First day it may deliver, in the advertiser's timezone: from 00:00 that day there, or from now if it is today. Omit to start from now.
    - `end_date` string: Last day, inclusive, in the advertiser's timezone (delivery stops at 23:59:59 that day).
    - `location_ids` string[], required: TikTok location ids from tiktok_search_targeting. Never a country or city name, and never a place together with a place inside it (a country and one of its cities) — TikTok refuses overlapping locations.
    - `age_groups` string[]: Age bands to target. Leave unset to reach every age TikTok allows, which includes 13–17 in most markets — pass the adult bands explicitly if the product is for adults only. In the US, Canada, Latin America, the EEA, the UK and Switzerland, TikTok limits an ad group that narrows by gender or interests to 18+, and refuses AGE_13_17 combined with them.
    - `gender` 'GENDER_UNLIMITED' | 'GENDER_MALE' | 'GENDER_FEMALE': Gender to target. Leave unset unless the product genuinely requires it.
    - `languages` string[]: Language codes exactly as tiktok_search_targeting (type: language) returns them, e.g. "en", "pt-BR". Checked against TikTok's list before anything is created.
    - `interest_category_ids` string[]: Interest category ids from tiktok_search_targeting (type: interest). Omit to let TikTok find the audience itself.
    - `interest_keyword_ids` string[]: Additional interest ids from tiktok_search_targeting (type: interest_keyword). Omit unless the user asked for a specific interest the categories do not cover.
    - `operating_systems` string[]: Target only one mobile operating system: ANDROID or IOS. TikTok takes a single value; leave unset for both.
    - `placement_type` 'PLACEMENT_TYPE_AUTOMATIC' | 'PLACEMENT_TYPE_NORMAL': PLACEMENT_TYPE_AUTOMATIC (default, and usually cheapest) or PLACEMENT_TYPE_NORMAL to choose placements, which then requires placements.
    - `placements` string[]: Which placements, required when placement_type is PLACEMENT_TYPE_NORMAL and ignored otherwise. PLACEMENT_PANGLE is off-app inventory; PLACEMENT_GLOBAL_APP_BUNDLE only reaches Brazil, Indonesia, Vietnam, the Philippines, Thailand, Malaysia, Mexico, Saudi Arabia and Japan.
    - `identity_id` string: Not used on the ad group: TikTok only takes an identity on Shopping ad groups, which Adako does not build. Pass the identity to tiktok_add_ad instead.
    - `identity_type` 'CUSTOMIZED_USER' | 'AUTH_CODE' | 'TT_USER' | 'BC_AUTH_TT': Not used on the ad group; pass it to tiktok_add_ad.
    - `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)