TikTok Ads Write
Update TikTok ad group settings: name, budget, targeting (age, gender, locations), schedule
POST https://api.adspirer.ai/api/v1/tools/update_tiktok_ad_group/execute
Authorization: Bearer sk_live_... — your Adspirer API key (required)Content-Type: application/json (required)Idempotency-Key: <uuid> — recommended for write operations to make retries safeAll tool arguments are wrapped in an arguments object.
| Field | Type | Description |
|---|---|---|
bid_type | string optional | Bid 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_price | number optional | Manual 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_price | number optional | Manual bid for conversions (oCPM target CPA). Required when objective=CONVERSIONS and bid_type=BID_TYPE_CUSTOM. Tells TikTok your target acquisition cost. |
bid_display_mode | string optional | Bid display mode: CPC, CPM, OCPM, CPV. Determines what the bid_price represents. Auto-set from billing_event when omitted. |
deep_bid_type | string optional | App-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_bid | number optional | App-campaign target deep-event cost. Used with deep_bid_type for purchase / signup / level-completion optimization beyond install. |
roas_bid | number optional | ROAS bidding target (e.g. 1.5 = 150% return on ad spend). Only valid for VALUE-based optimization on Shopping or Conversions. |
skip_learning_phase | boolean optional | Skip TikTok's mandatory 50-conversion learning phase. Off by default (recommended). Set true ONLY for retargeting an audience where behavior is already established. |
schedule_type | string optional | Schedule shape: SCHEDULE_FROM_NOW (continuous, no end), SCHEDULE_START_END (bounded). Auto-set when schedule_start_time/schedule_end_time are provided. |
dayparting | string optional | Hourly 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. |
frequency | integer optional | Max impressions per user. Required for REACH/AWARENESS objectives (TikTok rejects without it). Adspirer auto-defaults to 3 for REACH. |
frequency_schedule | integer optional | Frequency-cap window in days (1=daily, 7=weekly). Pairs with `frequency`. Auto-defaults to 7 for REACH. |
location_ids | array optional | TikTok location IDs (numeric strings). Default: ['6252001'] (US). Use search_tiktok_targeting to discover IDs by name. |
age_groups | array optional | Target age brackets: AGE_13_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45_54, AGE_55_100. Default: 18-100. |
gender | string optional | Target gender: GENDER_UNLIMITED (default), GENDER_MALE, GENDER_FEMALE. |
languages | array optional | Language codes (ISO-639): ['en'], ['es'], etc. Empty = no language filter. |
operating_systems | array optional | Target OS: ANDROID, IOS. Default: both. |
device_model_ids | array optional | TikTok device-model IDs for granular phone targeting (premium D2C, gaming). Use TikTok Ads Manager → Targeting → Device Models to browse the catalog. |
device_price_ranges | array optional | Phone 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_types | array optional | Connection types: WIFI, 2G, 3G, 4G, 5G. Default: all. Useful for video-heavy campaigns (set ['WIFI', '5G'] to ensure smooth playback). |
carrier_ids | array optional | Mobile carrier IDs for targeting. Useful for telco / app-promotion campaigns. Discover via TikTok Ads Manager → Targeting → Carriers. |
spending_power | string optional | In-platform spending tier: ALL (default), HIGH (top spenders only). Useful for luxury, premium subscription, high-AOV e-commerce. |
household_income | array optional | Household 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_ids | array optional | Contextual targeting tags — semantic content categories TikTok predicts the user is consuming. Discover via search_tiktok_targeting. |
audience_ids | array optional | Custom audience IDs to INCLUDE. Run list_tiktok_custom_audiences to discover. Customer-list, pixel-event, lookalike audiences all valid. |
excluded_audience_ids | array optional | Custom audience IDs to EXCLUDE (e.g. existing customers when running acquisition campaigns). |
audience_rule | object optional | Rule-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_type | string optional | Audience type filter: NORMAL, LOOKALIKE, ENGAGEMENT. Restricts which kinds of audiences match audience_ids. |
included_custom_actions | array optional | Engagement-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_actions | array optional | Engagement-based EXCLUDE actions (users who DID action X — e.g. exclude existing converters from acquisition campaigns). |
interest_category_ids | array optional | Top-level interest categories (TikTok's broad taxonomy). Discover via search_tiktok_targeting with targeting_type='interest_categories'. |
interest_keyword_ids | array optional | Granular interest-keyword IDs (more specific than categories). Discover via search_tiktok_targeting with targeting_type='interest_keywords'. |
interest_keywords | array optional | DEPRECATED 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_ids | array optional | Purchase-intent keyword IDs — users actively shopping for the topic. Higher-intent than interest keywords. Discover via search_tiktok_targeting. |
placement_type | string optional | PLACEMENT_TYPE_AUTOMATIC (TikTok picks placements) or PLACEMENT_TYPE_NORMAL (use `placements` field). |
placements | array optional | Manual 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_ids | array optional | App IDs to BLOCK from Pangle network delivery. Brand-safety filter preventing your ads from appearing in specific apps. |
included_pangle_audience_package_ids | array optional | Pangle audience-package IDs to INCLUDE. Pre-curated audience bundles TikTok offers for Pangle placement. |
excluded_pangle_audience_package_ids | array optional | Pangle audience-package IDs to EXCLUDE. |
brand_safety_partner | string optional | Third-party brand-safety integration: IAS, OPEN_SLATE. Required when brand_safety_type=THIRD_PARTY and placements=[PLACEMENT_TIKTOK]. |
brand_safety_type | string optional | Brand-safety filter: NO_BRAND_SAFETY (default), STANDARD_INVENTORY, LIMITED_INVENTORY, FULL_INVENTORY (Pangle only), THIRD_PARTY. Only valid when placements=[PLACEMENT_TIKTOK]. |
pixel_id | string optional | TikTok 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_event | string optional | Conversion 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_event | string optional | Secondary 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_retention | number optional | Day-1 retention ratio (0-1). For App campaigns optimizing on retention deep events. Formula: deep_cpa_bid / conversion_bid_price. |
conversion_id | string optional | Specific custom-conversion ID to optimize for (vs pixel event). Discover via TikTok Ads Manager → Custom Conversions. |
auto_targeting_enabled | string optional | Auto-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_expansion | object optional | Granular expansion controls: {'expansion_type_ids': [...], 'expand_age': true, 'expand_gender': true}. Tells TikTok which dimensions to broaden when auto-targeting. |
pacing | string optional | Budget pacing: PACING_MODE_SMOOTH (spread evenly across day, default) or PACING_MODE_FAST (spend as fast as possible). |
creative_material_mode | string optional | DCO creative-mode: CUSTOM (single creative, default), DYNAMIC (TikTok auto-optimizes across multiple uploaded creatives — pairs with create_tiktok_dco_ad). |
video_download_disabled | boolean optional | Block users from downloading the video creative. Useful for intellectual-property-sensitive content. |
comment_disabled | boolean optional | Disable comments on the ad. Useful for regulated industries (financial, healthcare) where unmoderated comments could create compliance issues. |
is_hfss | boolean optional | UK '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_type | string optional | Reporting attribution: ALL_DAY (default), 1D_VIEW + 7D_CLICK windows. Affects how conversions appear in TikTok reports — does not affect actual delivery / optimization. |
billing_event | string optional | Billing 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_goal | string optional | Optimization 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_type | string optional | Override promotion type: WEBSITE (default for most), APP_ANDROID, APP_IOS. Used by App-Promotion campaigns. |
adgroup_id | string required | TikTok ad group ID |
name | string optional | New ad group name (alias for adgroup_name). |
adgroup_name | string optional | New ad group name. |
budget | number optional | New budget in account currency |
schedule_end_time | string optional | End time: YYYY-MM-DD HH:MM:SS |
schedule_start_time | string optional | Start time: YYYY-MM-DD HH:MM:SS |
advertiser_id | string optional | TikTok advertiser ID. Required for multi-account users. Get from list_connected_accounts. |
{
"arguments": {
"adgroup_id": "string",
"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
}
}
{
"success": true,
"data": {
"text": "(tool-specific textual output for update_tiktok_ad_group)",
"quota": {
"used": 42,
"limit": 150,
"tier": "plus",
"period_end": "2026-05-01"
}
},
"tool": "update_tiktok_ad_group"
}
{
"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": "update_tiktok_ad_group"
}
{
"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": "update_tiktok_ad_group",
"quota": {
"used": 150,
"limit": 150,
"tier": "plus",
"period_end": "2026-05-01",
"upgrade_url": "https://adspirer.ai"
}
}
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