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
bid_typestring optionalBid strategy: BID_TYPE_NO_BID (auto, default), BID_TYPE_CUSTOM (manual bid), BID_TYPE_MAX_CONVERSION (cost cap). Use NO_BID for fastest learning; CUSTOM when a fixed CPA is required.
bid_pricenumber optionalManual bid amount per billing event (USD or account currency). Required when bid_type=BID_TYPE_CUSTOM. Used with billing_event=CPC/CPM/CPV.
conversion_bid_pricenumber optionalManual bid for conversions (oCPM target CPA). Required when objective=CONVERSIONS and bid_type=BID_TYPE_CUSTOM. Tells TikTok your target acquisition cost.
bid_display_modestring optionalBid display mode: CPC, CPM, OCPM, CPV. Determines what the bid_price represents. Auto-set from billing_event when omitted.
deep_bid_typestring optionalApp-campaign deep-event bidding: VO_MIN_ROAS (target ROAS), VO_MIN_DAY1_RETENTION, VO_MIN_DAY7_RETENTION. Only valid when objective=APP_PROMOTION. Pairs with deep_cpa_bid.
deep_cpa_bidnumber optionalApp-campaign target deep-event cost. Used with deep_bid_type for purchase / signup / level-completion optimization beyond install.
roas_bidnumber optionalROAS bidding target (e.g. 1.5 = 150% return on ad spend). Only valid for VALUE-based optimization on Shopping or Conversions.
skip_learning_phaseboolean optionalSkip TikTok's mandatory 50-conversion learning phase. Off by default (recommended). Set true ONLY for retargeting an audience where behavior is already established.
schedule_typestring optionalSchedule shape: SCHEDULE_FROM_NOW (continuous, no end), SCHEDULE_START_END (bounded). Auto-set when schedule_start_time/schedule_end_time are provided.
daypartingstring optionalHourly delivery mask. **336-character binary string** = 48 half-hour slots × 7 days (Mon-Sun). '1' = run, '0' = pause. Example: '0'*22 + '1'*4 + '0'*22 ... runs only at the encoded slots. TikTok's SDK docstring is wrong; the correct length is 336 (live-verified 2026-05-03). Do NOT confuse with the 96-char hourly format.
frequencyinteger optionalMax impressions per user. Required for REACH/AWARENESS objectives (TikTok rejects without it). Adspirer auto-defaults to 3 for REACH.
frequency_scheduleinteger optionalFrequency-cap window in days (1=daily, 7=weekly). Pairs with `frequency`. Auto-defaults to 7 for REACH.
location_idsarray optionalTikTok location IDs (numeric strings). Default: ['6252001'] (US). Use search_tiktok_targeting to discover IDs by name.
age_groupsarray optionalTarget age brackets: AGE_13_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45_54, AGE_55_100. Default: 18-100.
genderstring optionalTarget gender: GENDER_UNLIMITED (default), GENDER_MALE, GENDER_FEMALE.
languagesarray optionalLanguage codes (ISO-639): ['en'], ['es'], etc. Empty = no language filter.
operating_systemsarray optionalTarget OS: ANDROID, IOS. Default: both.
device_model_idsarray optionalTikTok device-model IDs for granular phone targeting (premium D2C, gaming). Use TikTok Ads Manager → Targeting → Device Models to browse the catalog.
device_price_rangesarray optionalPhone price tiers: [0]=<200 USD, [1]=200-400, [2]=400-600, [3]=600-800, [4]=>800. Multi-select supported (e.g. [3, 4] = premium phones only). Useful for luxury / premium-positioning campaigns.
network_typesarray optionalConnection types: WIFI, 2G, 3G, 4G, 5G. Default: all. Useful for video-heavy campaigns (set ['WIFI', '5G'] to ensure smooth playback).
carrier_idsarray optionalMobile carrier IDs for targeting. Useful for telco / app-promotion campaigns. Discover via TikTok Ads Manager → Targeting → Carriers.
spending_powerstring optionalIn-platform spending tier: ALL (default), HIGH (top spenders only). Useful for luxury, premium subscription, high-AOV e-commerce.
household_incomearray optionalHousehold income brackets (US-only). Values: 'TOP_5_PERCENT', 'TOP_10_PERCENT', 'TOP_25_PERCENT', 'TOP_50_PERCENT'. For price-positioned products that overindex on higher-income buyers.
contextual_tag_idsarray optionalContextual targeting tags — semantic content categories TikTok predicts the user is consuming. Discover via search_tiktok_targeting.
audience_idsarray optionalCustom audience IDs to INCLUDE. Run list_tiktok_custom_audiences to discover. Customer-list, pixel-event, lookalike audiences all valid.
excluded_audience_idsarray optionalCustom audience IDs to EXCLUDE (e.g. existing customers when running acquisition campaigns).
audience_ruleobject optionalRule-based audience definition (replaces fixed audience_ids). Pass an object like {'audience_op': 'union', 'audience_ids': ['x'], 'lookalike_audience_ids': ['y']}. See TikTok docs for full rule schema.
audience_typestring optionalAudience type filter: NORMAL, LOOKALIKE, ENGAGEMENT. Restricts which kinds of audiences match audience_ids.
included_custom_actionsarray optionalEngagement-based INCLUDE actions (users who did action X in last N days). Schema: [{'action_categories': ['VIDEO_VIEW'], 'days': 30}]. Useful for retargeting watchers + engagers without uploading audiences.
excluded_custom_actionsarray optionalEngagement-based EXCLUDE actions (users who DID action X — e.g. exclude existing converters from acquisition campaigns).
interest_category_idsarray optionalTop-level interest categories (TikTok's broad taxonomy). Discover via search_tiktok_targeting with targeting_type='interest_categories'.
interest_keyword_idsarray optionalGranular interest-keyword IDs (more specific than categories). Discover via search_tiktok_targeting with targeting_type='interest_keywords'.
interest_keywordsarray optionalDEPRECATED alias for interest_keyword_ids — TikTok does NOT resolve plain strings here; it requires pre-resolved numeric keyword IDs and rejects strings with 'Not a valid integer'. Use interest_keyword_ids instead, with IDs from search_tiktok_targeting (targeting_type='interest_keywords').
purchase_intention_keyword_idsarray optionalPurchase-intent keyword IDs — users actively shopping for the topic. Higher-intent than interest keywords. Discover via search_tiktok_targeting.
placement_typestring optionalPLACEMENT_TYPE_AUTOMATIC (TikTok picks placements) or PLACEMENT_TYPE_NORMAL (use `placements` field).
placementsarray optionalManual placements when placement_type=PLACEMENT_TYPE_NORMAL: PLACEMENT_TIKTOK (in-feed), PLACEMENT_PANGLE (audience network — allowlisted), PLACEMENT_GLOBAL_APP_BUNDLE. Always required even when AUTOMATIC (Adspirer auto-defaults to ['PLACEMENT_TIKTOK']).
blocked_pangle_app_idsarray optionalApp IDs to BLOCK from Pangle network delivery. Brand-safety filter preventing your ads from appearing in specific apps.
included_pangle_audience_package_idsarray optionalPangle audience-package IDs to INCLUDE. Pre-curated audience bundles TikTok offers for Pangle placement.
excluded_pangle_audience_package_idsarray optionalPangle audience-package IDs to EXCLUDE.
brand_safety_partnerstring optionalThird-party brand-safety integration: IAS, OPEN_SLATE. Required when brand_safety_type=THIRD_PARTY and placements=[PLACEMENT_TIKTOK].
brand_safety_typestring optionalBrand-safety filter: NO_BRAND_SAFETY (default), STANDARD_INVENTORY, LIMITED_INVENTORY, FULL_INVENTORY (Pangle only), THIRD_PARTY. Only valid when placements=[PLACEMENT_TIKTOK].
pixel_idstring optionalTikTok Pixel ID — must be the NUMERIC pixel ID (e.g. '1776777769'), NOT the alphanumeric Pixel Code (e.g. 'D7JNKABC...'). Find it in TikTok Ads Manager → Assets → Events → your pixel → 'Pixel ID' column.
optimization_eventstring optionalConversion event for CONVERSIONS objective. Valid set depends on the events configured on the pixel. Common: ON_WEB_ORDER (purchase), ON_WEB_CART, ON_WEB_DETAIL, ON_WEB_REGISTER, LANDING_PAGE_VIEW, CLICK_LANDING_PAGE, FORM, START_TRIAL, SUBSCRIBE, DOWNLOAD_FINISH, SEARCH. 'COMPLETE_PAYMENT' rejected by some advertisers — TikTok returns the exact accepted set in the rejection.
secondary_optimization_eventstring optionalSecondary funnel event used as a proxy when the primary event is too rare for ML to learn. E.g. when optimizing for ON_WEB_ORDER (purchase) and getting <50/week, set secondary=ON_WEB_CART so TikTok learns from the broader signal.
next_day_retentionnumber optionalDay-1 retention ratio (0-1). For App campaigns optimizing on retention deep events. Formula: deep_cpa_bid / conversion_bid_price.
conversion_idstring optionalSpecific custom-conversion ID to optimize for (vs pixel event). Discover via TikTok Ads Manager → Custom Conversions.
auto_targeting_enabledstring optionalAuto-broaden audience: 'ON' (default for many objectives) or 'OFF'. When ON, TikTok extends targeting beyond the explicit audience to users it predicts will convert.
targeting_expansionobject optionalGranular expansion controls: {'expansion_type_ids': [...], 'expand_age': true, 'expand_gender': true}. Tells TikTok which dimensions to broaden when auto-targeting.
pacingstring optionalBudget pacing: PACING_MODE_SMOOTH (spread evenly across day, default) or PACING_MODE_FAST (spend as fast as possible).
creative_material_modestring optionalDCO creative-mode: CUSTOM (single creative, default), DYNAMIC (TikTok auto-optimizes across multiple uploaded creatives — pairs with create_tiktok_dco_ad).
video_download_disabledboolean optionalBlock users from downloading the video creative. Useful for intellectual-property-sensitive content.
comment_disabledboolean optionalDisable comments on the ad. Useful for regulated industries (financial, healthcare) where unmoderated comments could create compliance issues.
is_hfssboolean optionalUK 'High Fat Salt Sugar' food classification (legal requirement for UK advertisers in food/drink categories). Enables age-gating and time restrictions per UK Advertising Code.
statistic_typestring optionalReporting attribution: ALL_DAY (default), 1D_VIEW + 7D_CLICK windows. Affects how conversions appear in TikTok reports — does not affect actual delivery / optimization.
billing_eventstring optionalBilling model override. CPC (cost per click), CPM (per 1000 impressions), OCPM (optimized for events), CPV (per video view). Adspirer picks objective-appropriate default; override only when you need a specific model.
optimization_goalstring optionalOptimization goal override. Adspirer auto-picks per objective: TRAFFIC→TRAFFIC_LANDING_PAGE_VIEW, CONVERSIONS→CONVERT, REACH→REACH, VIDEO_VIEWS→ENGAGED_VIEW (TikTok deprecated bare VIDEO_VIEW in 2026). Override only with a known-valid value — TikTok returns the accepted set on rejection.
promotion_typestring optionalOverride promotion type: WEBSITE (default for most), APP_ANDROID, APP_IOS. Used by App-Promotion campaigns.
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"
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.
advertiser_idstring optionalTikTok advertiser ID (optional).

Example request

{
  "arguments": {
    "campaign_id": "<campaign_id>",
    "adgroup_name": "string",
    "budget": 1.0,
    "bid_type": "string",
    "bid_price": 1.0,
    "conversion_bid_price": 1.0,
    "bid_display_mode": "string",
    "deep_bid_type": "string",
    "deep_cpa_bid": 1.0
  }
}

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