API Reference › TikTok Ads › add_tiktok_ad_group

add_tiktok_ad_group

TikTok Ads Write

Add a new ad group to an existing TikTok campaign

Endpoint

POST https://api.adspirer.ai/api/v1/tools/add_tiktok_ad_group/execute

Headers

Description

Add a new ad group to an existing TikTok campaign. Use this when you need to add additional ad groups to a campaign that was already created. Each ad group can have different targeting, budget, and placement settings. This is useful for: - A/B testing different audiences under the same campaign - Splitting budget across different targeting strategies - Adding new targeting segments to an existing campaign Required: campaign_id, adgroup_name, budget. The objective parameter determines automatic billing/optimization defaults (TRAFFIC→CPC, CONVERSIONS→OCPM, etc.). After creating the ad group, use `add_tiktok_ad` to add ads to it.

Request body

All tool arguments are wrapped in an arguments object.

FieldTypeDescription
campaign_idstring requiredExisting TikTok campaign ID to add the ad group to
adgroup_namestring requiredName for the new ad group
budgetnumber requiredAd group budget in account currency (min varies by region)
budget_modestring optionalBUDGET_MODE_DAY (daily) or BUDGET_MODE_TOTAL (lifetime). Default: daily. default: "BUDGET_MODE_DAY"
objectivestring optionalCampaign objective (determines billing/optimization defaults). Options: TRAFFIC, CONVERSIONS, LEAD_GENERATION, REACH, VIDEO_VIEWS, APP_PROMOTION. Default: TRAFFIC. default: "TRAFFIC"
location_idsarray optionalTikTok location IDs. Default: ['6252001'] (US).
age_groupsarray optionalAge groups: AGE_13_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45_54, AGE_55_100.
genderstring optionalGENDER_UNLIMITED, GENDER_MALE, GENDER_FEMALE.
schedule_start_timestring optionalStart time: YYYY-MM-DD HH:MM:SS.
schedule_end_timestring optionalEnd time: YYYY-MM-DD HH:MM:SS. Required for BUDGET_MODE_TOTAL.
pixel_idstring optionalTikTok Pixel ID for conversion tracking.
optimization_eventstring optionalConversion event: COMPLETE_PAYMENT, ON_WEB_CART, ON_WEB_DETAIL, ON_WEB_REGISTER, FORM, CONVERSION_LEADS, PAGE_VISIT, CLICK_LANDING_PAGE, PHONE_CONNECT, SEARCH, SUBSCRIBE, DOWNLOAD_FINISH.
interest_category_idsarray optionalInterest category IDs for targeting.
audience_idsarray optionalCustom audience IDs to include.
excluded_audience_idsarray optionalCustom audience IDs to exclude.
languagesarray optionalLanguage codes (e.g., ['en', 'es']).
placement_typestring optionalPLACEMENT_TYPE_AUTOMATIC or PLACEMENT_TYPE_NORMAL.
placementsarray optionalManual placements: PLACEMENT_TIKTOK, PLACEMENT_PANGLE, PLACEMENT_GLOBAL_APP_BUNDLE.
operating_systemsarray optionalTarget OS: ANDROID, IOS.
video_download_disabledboolean optionalDisable video download.
comment_disabledboolean optionalDisable comments on ads.
billing_eventstring optionalOverride billing event: CPC, CPM, OCPM, CPV.
optimization_goalstring optionalOverride optimization goal: CLICK, CONVERT, REACH, etc.
promotion_typestring optionalOverride promotion type: WEBSITE, APP_ANDROID, APP_IOS.
advertiser_idstring optionalTikTok advertiser ID (optional).

Example request

{
  "arguments": {
    "campaign_id": "<campaign_id>",
    "adgroup_name": "string",
    "budget": 1.0,
    "budget_mode": "BUDGET_MODE_DAY",
    "objective": "TRAFFIC",
    "location_ids": [
      "string"
    ],
    "age_groups": [
      "string"
    ],
    "gender": "string",
    "schedule_start_time": "string"
  }
}

Example responses

200 — Success

{
  "success": true,
  "data": {
    "text": "(tool-specific textual output for add_tiktok_ad_group)",
    "quota": {
      "used": 42,
      "limit": 150,
      "tier": "plus",
      "period_end": "2026-05-01"
    }
  },
  "tool": "add_tiktok_ad_group"
}

400 — Tool-level error (bad arguments / multi-account selection)

{
  "success": false,
  "error": "You have 25 meta_ads accounts connected. Please specify which account to use by passing the ad_account_id parameter:\n  - Acme Holdings (ad_account_id=\"act_123456789\")\n  - Acme EU (ad_account_id=\"act_987654321\")",
  "is_error": true,
  "tool": "add_tiktok_ad_group"
}

402 — Quota exhausted

{
  "success": false,
  "error": "\ud83d\udea8 Monthly limit reached (150/150 tool calls on Plus tier).\nUpgrade to Pro at https://adspirer.ai to keep building.",
  "is_error": true,
  "tool": "add_tiktok_ad_group",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}

Try it live

Interactive: Swagger UI

Machine-readable: OpenAPI 3.1 spec · llms-full.txt

More tools: TikTok Ads · All tools

Adspirer REST API — get an API key at adspirer.ai/keys · adspirer.ai