← 返回目录
📁 API Reference › Ad Groups

获取广告组

此接口可用于获取一个或多个广告组的详细信息。

可通过在请求中向 fields 字段传入所需信息，自定义该查询返回的信息。使用 filtering 字段传入要返回的广告组。支持的筛选条件包括推广系列 ID、推广目标、广告组 ID、广告组名称、广告组创建时间、计费事件和广告组状态。

注意
如果你希望查询中包含已删除的数据，在 primary_status 字段中传入 STATUS_DELETE 值，或在 secondary_status 字段中传入 ADGROUP_STATUS_DELETE /ADGROUP_STATUS_CAMPAIGN_DELETE。默认情况下，系统不会查询已删除的数据。

v1.2 与 v1.3 接口对比

下表概述了 v1.2 接口与 v1.3 接口之间的差异。 ``xtable |变更{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| |接口路径|/v1.2/adgroup/get/|/v1.3/adgroup/get/| |请求参数名称|create_start_time<br>create_end_time<br>status|creation_filter_start_time<br>creation_filter_end_time<br>secondary_status| |请求参数数据类型|advertiser_id: number<br>campaign_ids: number[]<br>adgroup_ids: number[]|advertiser_id: string <br>campaign_ids: string[]<br>adgroup_ids: string[]| |新增请求参数|/|promotion_type<br>exclude_field_types_in_response<br>creative_material_mode<br>bid_strategy<br>optimization_goal<br>campaign_system_origins<br>buying_types<br>split_test_enabled<br>campaign_automation_type| |返回参数名称|is_share_disable<br>placement<br>enable_inventory_filter<br>external_type<br>external_action<br>deep_external_action<br>age<br>operation_system<br>connection_type<br>device_price<br>android_osv<br>ios_target_device<br>ios_osv<br>optimize_goal<br>bid<br>conversion_bid<br>deep_cpabid<br>daily_retention_ratio<br>status<br>opt_status<br>action_v2<br>user_actions<br>rf_buy_type<br>buy_impression<br>buy_reach<br>rf_predict_cpr<br>rf_predict_frequency<br>include_custom_actions<br>exclude_custom_actions<br>dpa_retargeting_type<br>brand_safety<br>enable_expansion<br>ad_app_profile_page_type<br>display_mode|share_disabled<br>placements<br>inventory_filter_enabled<br>promotion_type<br>optimization_event<br>secondary_optimization_event<br>age_groups<br>operating_systems<br>network_types<br>device_price_ranges<br>min_android_version<br>ios14_targeting<br>min_ios_version<br>optimization_goal<br>bid_price<br>conversion_bid_price<br>deep_cpa_bid<br>next_day_retention<br>secondary_status<br>operation_status<br>actions<br>video_user_actions<br>rf_purchased_type<br>purchased_impression<br>purchased_reach<br>rf_estimated_cpr<br>rf_estimated_frequency<br>included_custom_actions<br>excluded_custom_actions<br>shopping_ads_retargeting_type<br>brand_safety_type<br>expansion_enabled<br>adgroup_app_profile_page_state<br>delivery_mode| |返回参数数据类型|advertiser_id: number<br>campaign_id: number<br>adgroup_id: number<br>app_id: number <br>store_id: number <br>pixel_id: number<br>skip_learning_phase: number<br>catalog_id: number<br>schedule_id: number |advertiser_id: string <br>campaign_id: string<br>adgroup_id: string<br>app_id: string <br>store_id: string<br>pixel_id: string <br>skip_learning_phase: boolean<br>catalog_id: string <br>schedule_id: string | |返回参数名称和数据类型|is_comment_disable: number<br>shop_authorized_bc: number<br>audience: number[]<br>excluded_audience: number[] <br>location: number[] <br>interest_category_v2: number[]<br>interest_keywords: number[] <br>device_models: number[]<br>carriers_v2: number[] <br>video_download: string <br>pangle_block_app_list_id: number[]<br>action_categories: number[] <br>pangle_audience_package_include: number[]<br>pangle_audience_package_exclude: number[]<br>catalog_authorized_bc: number<br>automated_targeting: string |comment_disabled: boolean<br>store_authorized_bc_id: string<br>audience_ids: string[] <br>excluded_audience_ids: string[]<br>location_ids: string[]<br>interest_category_ids: string[]<br>interest_keyword_ids: string[] <br>device_model_ids: string[] <br>carrier_ids: string[] <br>video_download_disabled: boolean <br>blocked_pangle_app_ids: string[]<br>action_category_ids: string[]<br>included_pangle_audience_package_ids: string[]<br>excluded_pangle_audience_package_ids: string[] <br>catalog_authorized_bc_id: string<br>auto_targeting_enabled: boolean | |新增返回参数|/ |shopping_ads_type<br>product_source<br>split_test_group_id<br>split_test_status<br>contextual_tag_ids<br>purchase_intention_keyword_ids<br>spending_power<br>zipcode_ids<br>isp_ids<br>category_exclusion_ids<br>vertical_sensitivity_id<br>is_smart_performance_campaign<br>search_result_enabled<br>click_attribution_window<br>view_attribution_window<br>attribution_event_count<br>shopping_ads_retargeting_custom_audience_relation<br>smart_audience_enabled<br>smart_interest_behavior_enabled<br>campaign_system_origin<br>engaged_view_attribution_window<br>vbo_window<br>predict_impression<br>topview_reach_range<br>pre_discount_cpm<br>cpm<br>discount_type<br>discount_amount<br>discount_percentage<br>pre_discount_budget<br>tiktok_subplacements<br>messaging_app_type<br>messaging_app_account_id<br>phone_region_code<br>phone_region_calling_code<br>phone_number<br>message_event_set_id<br>deep_funnel_optimization_status<br>deep_funnel_event_source<br>deep_funnel_event_source_id<br>deep_funnel_optimization_event<br>search_keywords<br>automated_keywords_enabled<br>app_config<br>custom_conversion_id<br>is_lhf_compliance<br>campaign_automation_type| |v1.3 中已弃用的返回参数|/ |carriers` |


## 请求
**地址** https://business-api.tiktok.com/open_api/v1.3/adgroup/get/


**方法** GET

**Header**

```xtable
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](1738373164380162.html)接口获取。 |

参数

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|advertiser_id {必填}|string| 广告主 ID。|
|fields |string[]| 要获取的字段。不传入时，默认返回所有字段。如需了解允许的字段，参见返回小节中 `list` 下的字段。|
|exclude_field_types_in_response| string[]|希望从返回结果中移除的字段类型。<br>允许的枚举值： <ul><li>`NULL_FIELD`：值为空的字段。</li></ul>|
|filtering |object|筛选条件。根据你的要求设置这些条件。如果未设置，将返回该广告主下的所有广告组。<br><br>示例：`filtering={"campaign_automation_type":"UPGRADED_SMART_PLUS"}`|
#| campaign_automation_type | string | 推广系列自动化类型。<br><br>枚举值：<ul><li>`MANUAL`：手动推广系列。</li><li>`SMART_PLUS`：Smart+ 推广系列。</li><li>`UPGRADED_SMART_PLUS`：升级版 Smart+ 推广系列，一种新的自动化推广系列类型。如需详细了解升级版 Smart+ 推广系列，参见[升级版 Smart+ 推广系列](1853452461203458.html)。</li></ul> |
#|campaign_ids |string[]| 推广系列 ID 列表。<br>最大数量：100。 |
#| campaign_system_origins| string[] | 广告组所属的推广系列的来源。<br> <br> 枚举值： <ul><li>`PROMOTE`：该推广系列是通过 TikTok 手机应用、使用推广功能创建的推广系列。</li><li>`TT_ADS_PLATFORM`：该推广系列是通过 API 或在 TikTok 广告管理平台中、未使用推广功能创建的推广系列。 </li></ul> 默认值：`["TT_ADS_PLATFORM"]`。<br><br>仅可获取推广广告组的以下设置： <ul><li>`advertiser_id`</li><li>`campaign_id`</li><li> `campaign_name`</li><li>`adgroup_id` </li><li>`adgroup_name` </li><li>`create_time`</li><li>`budget` </li><li>`schedule_type`</li><li>`schedule_start_time`</li><li> `schedule_end_time`</li><li>`operation_status`</li><li>`secondary_status`</li></ul><br>如需详细了解推广广告组的可用性和支持的筛选条件，参见[使用推广功能创建的推广系列](1785880454546433.html)。 |
#|adgroup_ids |string[]| 广告组 ID 列表。<br>最大数量：100。 |
#|adgroup_name |string|广告组名称。 |
#|primary_status |string|一级状态。枚举值参见[枚举值 - 一级状态](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。默认值为 `STATUS_NOT_DELETE`，会返回除 `STATUS_DELETE` 之外所有状态的广告组。若想获取包括 `STATUS_DELETE` 在内的所有状态的广告组，需使用 `STATUS_ALL`。|
#|secondary_status|string| 广告组二级状态。枚举值参见[枚举值 - 广告组状态 - 二级状态](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。 <br><p><span style="color:darkred"><b>注意</b></span>： <ul><li>在沙箱环境中不会返回此字段，因为广告组实际未投放。</li><li>如需了解针对你传入的一级状态，可通过 `secondary_status` 传入的合法值，参见[一级状态下支持的二级状态](https://ads.tiktok.com/marketing_api/docs?id=1757239620352002)。</li></ul>|
#|objective_type |string| 推广目标。<br><br>详细信息参见[枚举值 - 推广目标](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。<br><br><p><span style="color:darkred"><b>注意</b></span>：无论选择 `WEB_CONVERSIONS` 还是  `CONVERSIONS` 作为推广目标筛选条件，均会返回 `WEB_CONVERSIONS` 和  `CONVERSIONS` 数据。  |
#| buying_types | string[] | 按购买类型筛选。<br><br>枚举值： <ul><li> `AUCTION`：竞价广告。 </li><li>`RESERVATION_RF`：合约覆盖和频次广告、TikTok Pulse 广告。</li><li>`RESERVATION_TOP_VIEW`：合约 TopView 广告。</li></ul><br>默认值：`["AUCTION", "RESERVATION_RF"]`。<br><br>如需详细了解 TopView 广告在 API 中的可用性，参见 [TopView](1804258360285186.html)。 <br><br><p><span style="color:darkred"><b>注意</b></span>：枚举值 `RESERVATION_TOP_VIEW` 不能与其他值一起使用。若想筛选 TopView 广告，需将此字段设置为 `["RESERVATION_TOP_VIEW"]`。 |
#|optimization_goal|string|优化目标。  枚举值：  [枚举值 - 优化目标](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138#item-link-Optimization%20Goal)。|
#|promotion_type |string| 希望作为筛选条件的推广类型（优化位置）。<br>枚举值： <ul><li>`APP`：应用。 </li><li>`WEBSITE`：落地页。 </li><li>`INSTANT_FORM`：即时表单。 </li><li>`LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE`：TikTok 私信。</li><li>`LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE`：社交媒体应用。  </li><li> `LEAD_GEN_CLICK_TO_CALL`：电话通话。 </li></ul><br><p><span style="color:darkred"><b>注意</b></span>： <ul><li> 此筛选字段与用于广告组创建的 `promotion_type` 不同，后者也会在该接口中返回。在同步基础报表和同步 DSA 报表中，也支持将 `promotion_type` 用作筛选条件。</li><li> 如需了解如何设置此字段以筛选在创建广告组时使用的某些推广类型，参见[附录 - 不同推广对象类型之间的映射](https://ads.tiktok.com/marketing_api/docs?id=1758485431181314)。</li></ul> |
#|bid_strategy |string| 出价策略。枚举值：`BID_STRATEGY_COST_CAP`、`BID_STRATEGY_BID_CAP`、`BID_STRATEGY_MAX_CONVERSION` 和 `BID_STRATEGY_LOWEST_COST`|
#|creative_material_mode |string| 创意的投放策略。  <br><br>枚举值：`CUSTOM`（自定义）、`SMART_CREATIVE`（智能创意）。 |
#|billing_events |string[]|你希望为之付费的事件。 枚举值参见[枚举值 - 计费事件](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
#|creation_filter_start_time |string|按广告组创建时间范围的下限进行筛选，格式为 `YYYY-MM-DD HH:MM:SS`（UTC 时区）。在该时间之后创建的广告组将返回。<br>建议：应用创建时间筛选条件时，建议将时间范围控制在 6 个月内，以免影响任务的成功率和执行速度。|
#|creation_filter_end_time|string|按广告组创建时间范围的上限进行筛选，格式为 `YYYY-MM-DD HH:MM:SS`（UTC 时区）。在该时间之前创建的广告组将返回。<br>建议：应用创建时间筛选条件时，建议将时间范围控制在 6 个月内，以免影响任务的成功率和执行速度。|
#|split_test_enabled|boolean|根据广告组是否启用拆分对比测试进行筛选。<br>`true`：仅获取已启用拆分对比测试的广告组，`false`：仅获取未启用拆分对比测试的广告组。 <br><p><span style="color:darkred"><b>注意</b></span>：如果不传入此字段，将获取所有广告组。|
|page |number|当前页码。<br><br>默认值：1。值范围：≥ 1。|
|page_size |number|页面大小。<br><br>默认值：10。值范围：1-1,000。<br><br><p><span style="color:darkred"><b>注意</b></span>：如果在筛选字段 `buying_types` 中使用枚举值 `RESERVATION_TOP_VIEW`，可为此字段传入的最大值为 100。 |

示例

获取广告账号中未被删除的广告组

(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/adgroup/get/?advertiser_id={{advertiser_id}}' \
--header 'Access-Token: {{Access-Token}}'

(/code)

获取广告账号中的所有广告组

(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/adgroup/get/?advertiser_id={{advertiser_id}}&filtering={"primary_status":"STATUS_ALL"}' \
--header 'Access-Token: {{Access-Token}}'

(/code)

获取特定推广系列中的广告组

(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/adgroup/get/?advertiser_id={{advertiser_id}}&filtering={"campaign_ids":["{{campaign_id}}"]}' \
--header 'Access-Token: {{Access-Token}}'

(/code)

获取特定时间范围内创建的广告组

(code curl http)
curl --location --request GET  'https://business-api.tiktok.com/open_api/v1.3/adgroup/get/?advertiser_id={{advertiser_id}}&filtering={"creation_filter_start_time":"2024-01-01 00:00:00","creation_filter_end_time":"2024-01-30 00:00:00"}' \
--header 'Access-Token: {{Access-Token}}'

(/code)

返回

|字段{30%}|类型{15%}|描述{55%}|
|-|-|-|
|code |number|返回码。完整返回码列表及描述参见[附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string|返回信息。更多信息参见[附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。 |
|request_id |string|请求的日志 ID，唯一标识一个请求。|
|data |object|返回数据。默认情况下，返回的列表会按广告组 ID (`adgroup_id`) 倒序排序。 <br><br><p><span style="color:darkred"><b>注意</b></span>：通过 TikTok Shop 创建的[商品 GMV Max 广告](https://ads.tiktok.com/help/article/about-automated-product-ads?lang=en)和直播 GMV Max 广告的数据不包含在返回结果中。通过 API 或 TikTok 广告管理平台创建的购物广告不受影响。|
#|list |object[]|数据列表。返回字段根据请求参数中的 `fields` 字段生成。如果不在请求中传入，默认返回所有字段。|
##|advertiser_id |string|广告主 ID|
##|campaign_id |string| 推广系列 ID |
##|campaign_name |string|广告组所属的推广系列的名称。|
##| campaign_system_origin | string | 仅当为推广广告组时返回。<br>对于非推广广告组，不返回此字段。<br><br>广告组所属的推广系列的来源。<br><br>枚举值： <ul><li> `PROMOTE`：该推广系列是通过 TikTok 手机应用、使用推广功能创建的推广系列。</li></ul> <br>仅可获取推广广告组的以下设置（推广系列层级的 `campaign_system_origin` 为 `PROMOTE`）： <ul><li>`advertiser_id`</li><li>`campaign_id`</li><li> `campaign_name`</li><li>`adgroup_id` </li><li>`adgroup_name` </li><li>`create_time`</li><li>`budget` </li><li>`schedule_type`</li><li>`schedule_start_time`</li><li> `schedule_end_time`</li><li>`operation_status`</li><li>`secondary_status`</li></ul>|
##| campaign_automation_type | string | 推广系列自动化类型。<br><br>枚举值：<ul><li>`MANUAL`：手动推广系列。</li><li>`SMART_PLUS`：Smart+ 推广系列。</li><li>`UPGRADED_SMART_PLUS`：升级版 Smart+ 推广系列，一种新的自动化推广系列类型。如需详细了解升级版 Smart+ 推广系列，参见[升级版 Smart+ 推广系列](1853452461203458.html)。</li></ul> |
##| is_smart_performance_campaign | boolean | 推广系列是否属于自动化推广系列类型。<br><br>支持的值：<ul><li>`true`：推广系列为旧版 Smart+ 推广系列。</li><li>`false`：推广系列为手动推广系列或升级版 Smart+ 推广系列。<ul><li>若想确定推广系列是手动推广系列还是升级版 Smart+ 推广系列，需查看返回的 `campaign_automation_type`。<ul><li>当 `campaign_automation_type` 为 `MANUAL` 时，为手动推广系列。</li><li>当 `campaign_automation_type` 为 `UPGRADED_SMART_PLUS` 时，为升级版 Smart+ 推广系列。</li></ul></li></ul></li></ul> |
##|adgroup_id |string| 广告组 ID |
##|adgroup_name |string| 广告组名称|
##| create_time | string | 广告组创建时间，格式为 `"YYYY-MM-DD HH:MM:SS"`。<br><br>示例：`"2023-01-01 00:00:01"`。 |
##| modify_time | string | 广告组修改时间，格式为 `"YYYY-MM-DD HH:MM:SS"`。  <br><br>示例：`"2023-01-01 00:00:01"`。 |
##|shopping_ads_type|string|当推广系列层级的 `objective_type` 为 `PRODUCT_SALES` 时返回。<br><br>购物广告类型。<br><br>枚举值： <ul><li>`VIDEO`：视频购物广告。</li><li>`LIVE`：直播购物广告。</li><li>`PRODUCT_SHOPPING_ADS`：商品购物广告。</li><li>`CATALOG_LISTING_ADS`：商品库详情广告。</li><li>`UNSET`：未设置。</li></ul>|
##|identity_id |string|当 `shopping_ads_type` 为 `VIDEO` 且 `product_source` 为 `SHOWCASE` 或 `shopping_ads_type` 为 `LIVE` 时返回。<br><br>广告发布身份 ID。 |
##|identity_type|string|当 `shopping_ads_type` 为 `VIDEO` 且 `product_source` 为 `SHOWCASE` 或 `shopping_ads_type` 为 `LIVE` 时返回。<br><br>广告发布身份类型。枚举值：`AUTH_CODE`（授权帖子用户）、`TT_USER`（TikTok 企业号用户）、`BC_AUTH_TT`（商务中心有权访问的 TikTok 账号）。当 `objective_type` 为 `PRODUCT_SALES` 时返回。详细信息参见[认证身份](https://ads.tiktok.com/marketing_api/docs?id=1738958351620097)。 |
##|identity_authorized_bc_id|string|当 `identity_type` 为 `BC_AUTH_TT` 时返回。<br><br>  与作为商务中心广告发布身份的 TikTok 账号用户关联的商务中心 ID。  |
##|product_source|string|当为视频购物广告和商品购物广告时返回。<br><br>用于获取推广商品的商品来源。<br>枚举值：`UNSET`、`CATALOG`（商品库）、`STORE` (TikTok Shop)、`SHOWCASE`（TikTok 橱窗）。|
##|catalog_id|string| 在以下任意场景中返回：<ul><li>`product_source` 为 `CATALOG` 或 `STORE`。</li><li>`shopping_ads_type` 为 `LIVE`，并且此字段已在请求中传入。</li></ul><br>商品库 ID。<br><br><p><span style="color:darkred"><b>注意</b></span>：自 2024 年 6 月 30 日起，对于 `product_source` 为 `STORE` 的新建购物广告，不再返回 `catalog_id`，因为传入的 `catalog_id` 将被忽略。`product_source` 为 `STORE` 的现有购物广告不会受到影响，除非你进行更新。如果你更新现有广告组，这些广告组的现有 `catalog_id`（如有）将不再返回。|
##|catalog_authorized_bc_id|string| 在以下任意场景中返回：<ul><li>`shopping_ads_type` 为 `VIDEO` 且 `product_source` 为 `CATALOG` 或 `STORE`。</li><li>`shopping_ads_type` 为 `LIVE`，并且此字段已在请求中传入。</li></ul><br>对于商务中心内的商品库，此字段返回商品库所属商务中心的 ID。<br><br><p><span style="color:darkred"><b>注意</b></span>：自 2024 年 6 月 30 日起，对于 `product_source` 为 `STORE` 的新建购物广告，不再返回 `catalog_authorized_bc_id`，因为传入的 `catalog_authorized_bc_id` 将被忽略。`product_source` 为 `STORE` 的现有购物广告不会受到影响，除非你进行更新。如果你更新现有广告组，这些广告组的现有 `catalog_authorized_bc_id`（如有）将不再返回。|
##|store_id |string| 在以下任意场景中返回：<ul><li>`shopping_ads_type` 为 `VIDEO` 且 `product_source` 为 `STORE`。</li><li>`shopping_ads_type` 为 `PRODUCT_SHOPPING_ADS` 且 `product_source` 为 `STORE`。</li><li>`shopping_ads_type` 为 `LIVE`，并且此字段已在请求中传入。</li></ul><br>TikTok Shop 的 ID。  |
##|store_authorized_bc_id |string|当传入 `store_id` 时返回。<br><br>经授权可访问店铺 (`store_id`) 的商务中心 ID。 |
##|promotion_type |string|推广类型（优化位置）。<br>你可以使用此字段来选择商品推广的投放位置。如需了解值的定义，参见[枚举值 - 推广类型](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。 |
##|promotion_target_type |string| 线索收集推广目标的推广类型。<br>枚举值： <ul><li> `INSTANT_PAGE`：即时表单。创建可快速加载的应用内 TikTok 即时表单来收集更多线索。</li><li> `EXTERNAL_WEBSITE`：网站表单。使用包含网站表单的落地页，或使用 TikTok 即时体验页面（可跳转到包含网站表单的网站），收集更多线索。 </li><li>`UNSET`。</li></ul> |
##| messaging_app_type | string | 要在即时通讯广告组中使用的即时通讯应用或自定义 URL 的类型。<br><br>枚举值： <ul><li> `MESSENGER`：Messenger。 </li><li>`WHATSAPP`：WhatsApp。</li><li>`ZALO`：Zalo。 </li><li>`LINE`：Line。</li><li>`IM_URL`：即时通讯 URL。</li></ul>|
##| messaging_app_account_id | string | 即时通讯应用账号的 ID。<ul><li>当 `messaging_app_type` 为 `MESSENGER` 时，此字段表示 Facebook 公共主页编号。</li><li>当 `messaging_app_type` 为 `LINE` 时，此字段表示 LINE 企业 ID。</li><li>当 `messaging_app_type` 为 `WHATSAPP` 时，此字段表示根据传入的 `phone_region_code`、`phone_region_calling_code` 和 `phone_number` 自动填充的 WhatsApp 电话号码。</li></ul>|
##| phone_region_code | string | WhatsApp 电话号码或 Zalo 电话号码的地区代码。<br><br>示例：`US`。 |
##| phone_region_calling_code | string | WhatsApp 电话号码或 Zalo 电话号码的国际区号。<br><br>示例：`+1`。 |
##| phone_number | string | WhatsApp 电话号码或 Zalo 电话号码。 |
##|promotion_website_type|string|广告组中的 TikTok 即时体验页面类型。  <br>枚举值：<ul><li>`UNSET`：不使用 TikTok 即时体验页面。 </li><li>`TIKTOK_NATIVE_PAGE`：使用 TikTok 即时体验页面。  </li></ul>|
##|app_id |string|待推广应用的 ID。你可以通过 [/app/list/](https://ads.tiktok.com/marketing_api/docs?id=1740859313270786) 接口获取 `app_id`。|
##|app_type |string| 所推广应用的类型。枚举值：`APP_ANDROID` (Android)、`APP_IOS` (iOS)。|
##|app_download_url |string|应用下载链接|
##|pixel_id |string|Pixel ID。仅适用于落地页。 |
##|optimization_event |string|广告组的转化事件。更多信息参见[转化事件](https://ads.tiktok.com/marketing_api/docs?id=1739361474981889)。 |
##|custom_conversion_id|string|用于广告组的自定义转化的 ID。|
##| app_config | object[] | 当推广系列层级的 `sales_destination` 为 `WEB_AND_APP` 时返回。<br><br>  待推广的一个或多个应用的详细信息。 |
###| app_id | string | 待推广应用的 ID。 |
##| deep_funnel_optimization_status | string | 深层漏斗优化的状态。<br>通过深层漏斗优化，你可以在主要优化事件之外再选择一个次要事件，这有助于提升推广系列的效果。 <br><br>枚举值： <ul><li>`ON`：已启用。 </li><li> `OFF`：未启用。 </li></ul>|
##| deep_funnel_event_source| string | 当 `deep_funnel_optimization_status` 为 `ON` 时返回。 <br><br>事件源类型。<br><br>枚举值： <ul><li>`PIXEL`：Pixel。 </li><li>`OFFLINE`：线下事件组。 </li><li>`CRM`：CRM 事件组。</li></ul> |
##| deep_funnel_event_source_id | string | 当 `deep_funnel_optimization_status` 为 `ON` 时返回。<br><br>事件源 ID。 <br><br><ul><li>当 `deep_funnel_event_source` 为 `PIXEL` 时，此字段表示 Pixel ID。</li><li>当 `deep_funnel_event_source` 为 `OFFLINE` 时，此字段表示线下事件组 ID。 </li><li>当 `deep_funnel_event_source` 为 `CRM` 时，此字段表示 CRM 事件组 ID。</li></ul> |
##| deep_funnel_optimization_event | string | 当 `deep_funnel_optimization_status` 为 `ON` 时返回。 <br><br>深层漏斗优化事件。 <br><br>示例：`SHOPPING`。 |
##|placement_type |string|决定你的广告将在哪里展示的广告位策略。枚举值：`PLACEMENT_TYPE_AUTOMATIC`（自动广告位）、`PLACEMENT_TYPE_NORMAL`（选择广告位）。|
##|placements | string[] | 你希望投放广告的应用。枚举值参见[枚举值 - 广告位](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。 <br><p><span style="color:darkred"><b>注意</b></span>： <ul><li> 如果广告组的 `placement_type` 为 `PLACEMENT_TYPE_AUTOMATIC`（自动广告位），此字段将返回你的推广目标支持的广告位。例如，如果实际支持的广告位只有 TikTok，此字段返回的值将为 `PLACEMENT_TIKTOK`。 <ul><li> 但是，如果你的推广目标支持 `PLACEMENT_GLOBAL_APP_BUNDLE`，而你并未加入全球化应用组合广告位功能的白名单，那么此字段返回的值中将不会包含 `PLACEMENT_GLOBAL_APP_BUNDLE`。</li></ul></li><li> 如果广告组的 `placement_type` 为 `PLACEMENT_TYPE_NORMAL`（选择广告位），此字段通常会返回你在请求中通过 `placements` 传入的广告位。 <ul><li> 唯一的例外情况是，如果在请求中通过 `placements` 传入 `PLACEMENT_GLOBAL_APP_BUNDLE`，但你并未加入全球化应用组合广告位功能的白名单，那么此字段返回的值中将排除 `PLACEMENT_GLOBAL_APP_BUNDLE`。例如，如果你在请求中传入的广告位为 `["PLACEMENT_TIKTOK", "PLACEMENT_GLOBAL_APP_BUNDLE"]`，但你并未加入全球化应用组合的白名单，那么此字段返回的值将为 `["PLACEMENT_TIKTOK"]`。 </li></ul> </li></ul>|
##| tiktok_subplacements | string[] | TikTok 内的下级广告位，可供你选择广告的展示位置。<br><br>枚举值： <ul><li>`IN_FEED`：信息流。广告将投放在推荐页信息流中，也可能会投放在主页和关注页信息流中。</li><li>`SEARCH_FEED`：搜索信息流。</li><li>`TIKTOK_LITE`：TikTok Lite，精简版 TikTok，应用体积更小，视频加载速度更快。TikTok Lite 下级广告位目前仅支持定向日本或韩国。</li><li>`LEMON8`：Lemon8，一款生活方式内容社区应用，内容包含真实生活体验分享、小贴士、指南和商品测评。如果选择 Lemon8 作为下级广告位，广告将展示在其推荐页信息流、搜索信息流和沉浸式视频信息流中。[详细了解 Lemon8](https://ads.tiktok.com/help/article/about-lemon8-in-tiktok-ads-manager)</a>。</li></ul><br><p><span style="color:darkred"><b>注意</b></span>：如果在创建广告组时不传入 `tiktok_subplacements`，此字段的值将为空列表 (`[]`)。 |
##| search_result_enabled | boolean | 是否在搜索广告中包含你的广告，即当用户在 TikTok 上搜索你的业务相关信息时向其展示你的广告。 |
##|automated_keywords_enabled| boolean |是否启用自动关键词，让系统在你添加广告后自动生成关键词。这有助于扩展优质流量，进而提升效果。你可以在报告中查看效果出色的自动关键词。<br><br>支持的值：`true`、`false`。 |
##|search_keywords|object[] |仅当为搜索推广系列时返回。<br><br>搜索关键词列表，即用于将你的广告与用户正在搜索的词语进行匹配的单词或词组。 |
###|keyword | string | 搜索关键词。 |
###|match_type | string | 搜索关键词的匹配类型。<br><br>枚举值：<ul><li>`PRECISE_WORD`：精确匹配。仅当用户的搜索查询与这些关键词完全匹配时，才会展示你的广告。</li><li>`PHRASE_WORD`：词组匹配。仅当用户按相同词序搜索这些特定关键词时，才会展示你的广告。</li><li>`BROAD_WORD`：广泛匹配。即使用户按不同词序进行搜索查询，只要包含你设置的任意关键词，就会展示你的广告。</li></ul> |
###|keyword_bid_type | string | 关键词和匹配类型组合的出价类型。<br><br>枚举值：<ul><li>`FOLLOW_ADGROUP`：使用广告组层级出价 (`bid_price`) 作为 `keyword_bid`。</li><li>`CUSTOM`：通过 `keyword_bid` 自定义出价。</li></ul> |
###|keyword_bid | float | 关键词和匹配类型组合的出价。 |
###|audit_status | string | 搜索关键词的审核状态。<br><br>枚举值：<ul><li>`AUDITING`：正在审核关键词。</li><li>`PASS`：关键词已通过审核，可以投放。</li><li>`REJECTED`：关键词未通过审核，无法投放。</li></ul>|
###|reject_info | object[] | 仅当 `audit_status` 为 `REJECTED` 时返回。<br><br>审核未通过的详细信息。|
####|forbidden_location| string |未通过审核的定向地区。<br><br>枚举值参见[附录 - 地区代码](1737585867307010.html)。|
####|reject_reasons| object[] |被拒原因列表。|
#####|reason| string |被拒原因。 |
##|comment_disabled |boolean|是否允许在 TikTok 上评论你的广告。  |
##|video_download_disabled |boolean| 用户是否可以在 TikTok 上下载你的视频广告。 |
##|share_disabled|boolean|是否禁止将此广告组中的广告分享到第三方平台。 |
##|blocked_pangle_app_ids |string[]|Pangle 应用屏蔽列表 ID。|
##|audience_type |string| 应用再营销受众类型。枚举值参见[枚举值 - 应用再营销受众类型](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。 |
##|audience_rule |object| 传入受众的规则。  |
##|auto_targeting_enabled{-To be deprecated}|boolean|是否启用自动定向。 <br><br><p><span style="color:darkred"><b>注意</b></span>： 自 2024 年 6 月起，你无法再为广告组启用自动定向或定向拓量功能。为确保 API 集成顺利进行，建议迁移到[智能定向](1783164662979586.html)。 |
##| shopping_ads_retargeting_type | string | 当 `shopping_ads_type` 为 `VIDEO` 且 `product_source` 为 `CATALOG` 时返回。<br><br>购物广告的再营销类型。枚举值： <ul><li>`LAB1`：对已浏览商品或将商品加入购物车但未购买的受众进行再营销。 </li><li>`LAB2`：对已将商品加入购物车但未购买的受众进行再营销。 </li><li>`LAB3`：使用自定义组合对受众进行再营销。 </li><li>`OFF`：不进行再营销。 </li></ul> |
##| shopping_ads_retargeting_actions_days | number | 所传入受众操作的合法时间范围。购物广告将对在此时间范围内完成所传入操作的受众进行再营销。<br><br>值范围：1、2、3、7、14、30、60、90、180。 |
##| included_custom_actions | object[] | 用作“包含”条件以筛选购物广告再营销受众的自定义操作。|
###| code | string | 用于筛选再营销受众的自定义操作。枚举值： <ul><li>`VIEW_PRODUCT`：受众浏览了商品。 </li><li>`ADD_TO_CART`：受众将商品加入了购物车。 </li><li>`PURCHASE`：受众购买了商品。 </li></ul>|
###| days | integer | 用于筛选已完成所传入操作的受众的时间范围。值范围：[1,180]。 |
##| excluded_custom_actions | object[] | 用作“排除”条件以筛选购物广告再营销受众的自定义操作。|
###| code | string | 用于筛选再营销受众的自定义操作。枚举值： <ul><li>`VIEW_PRODUCT`：受众浏览了商品。 </li><li>`ADD_TO_CART`：受众将商品加入了购物车。 </li><li>`PURCHASE`：受众购买了商品。 </li></ul>|
###| days | integer | 用于筛选未完成所传入操作的受众的时间范围。值范围：[1,180]。 |
##| shopping_ads_retargeting_custom_audience_relation | string | 通过 `shopping_ads_retargeting_type` 传入的视频购物广告 (VSA) 再营销受众与通过 `audience_ids` 传入的自定义受众之间的逻辑关系。<br><br>枚举值： <ul><li>`OR`：基于 VSA 再营销受众和自定义受众的并集创建目标受众。目标受众将由属于 VSA 再营销受众或自定义受众的用户组成。 </li><li>`AND`：基于 VSA 再营销受众和自定义受众的交集创建目标受众。目标受众将由既属于 VSA 再营销受众又属于自定义受众的用户组成。 </li></ul>|
##|location_ids |string[]|定向地域的 ID。 |
##| zipcode_ids|string[]|定向地域的邮政编码 ID。 <br><p><span style="color:darkred"><b>注意</b></span>：<ul><li> 邮政编码定向目前仅在美国、加拿大、巴西、印度尼西亚、泰国和越南可用。 </li><li> 若想获取关于邮政编码 ID 的信息，只能使用 [/tool/targeting/info/](https://ads.tiktok.com/marketing_api/docs?id=1761237001980929) 接口。</li></ul>|
##|languages |string[]|你希望定向的语言的代码。支持的语言代码列表参见[枚举值 - 语言代码](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
##|gender |string|你希望定向的性别。枚举值：`GENDER_FEMALE`、`GENDER_MALE`、`GENDER_UNLIMITED`|
##|age_groups |string[]|你希望定向的年龄组。枚举值参见[枚举值 - 受众年龄区间](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
##|spending_power|string|你希望定向的消费能力。枚举值：`ALL`、`HIGH`。  如果该值设置为 `HIGH`，你可以定向高消费用户，这些用户在 TikTok 广告引导下的购买支出通常高于平均水平。|
##|household_income| string[]| 你希望定向的家庭收入。枚举值：`TOP5`（邮政编码地区的前 5%）、`TOP10`（邮政编码地区的前 10%）、`TOP10_25`（邮政编码地区的前 10% - 25%）、`TOP25_50`（邮政编码地区的前 25% - 50%）。  |
##|audience_ids|string[]|受众 ID 列表。 |
##| smart_audience_enabled | boolean | 是否启用智能受众。<br><br>枚举值：`true`、`false`。<br><br>如需详细了解智能受众以及如何启用智能受众，参见[智能定向](1783164662979586.html)。 |
##|excluded_audience_ids |string[]|已排除的受众 ID 列表。|
##|interest_category_ids |string[]|你希望用来定向受众的大众兴趣关键词 ID。 |
##|interest_keyword_ids|string[]|你希望用来定向受众的其他兴趣关键词 ID。 |
##|purchase_intention_keyword_ids|string[]|在受众对特定内容类别的相关购买感兴趣时，用于对其进行定向的购买意向类别 ID。|
##|actions| object[] | 用于广告定向的行为类别对象列表。|
###|action_scene | string | 你希望定向的用户行为类别。<br><br>枚举值： <ul><li>`VIDEO_RELATED`：视频互动。</li><li>`CREATOR_RELATED`：创作者互动。</li><li>`HASHTAG_RELATED`：话题互动。</li></ul>|
###|action_period |number| 将统计用户行为的时间段。  |
###|video_user_actions|string[]| 在某个用户行为类型下，你希望定向的具体用户互动。<br><br><ul><li>如果 `action_scene` 为 `VIDEO_RELATED`，允许的值为：`WATCHED_TO_END`、`LIKED`、`COMMENTED`、`SHARED`。</li><li> 如果 `action_scene` 为 `CREATOR_RELATED`，允许的值为：`FOLLOWING`、`VIEW_HOMEPAGE`。 </li><li>如果 `action_scene` 为 `HASHTAG_RELATED`，允许的值为 `VIEW_HASHTAG`。</li></ul> |
###|action_category_ids |string[]|你希望用来定向受众的视频互动类别 ID、创作者互动类别 ID、话题 ID 或话题汇总 ID。|
##| smart_interest_behavior_enabled | boolean | 是否启用智能兴趣和行为。<br><br>枚举值：`true`、`false`。<br><br>如需详细了解智能兴趣和行为以及如何启用智能兴趣和行为，参见[智能定向](1783164662979586.html)。 |
##|included_pangle_audience_package_ids |string[]| 你希望包含的 Pangle 受众 ID。仅当为 Pangle 广告位时生效。你可以使用 [/pangle_audience_package/get/](https://ads.tiktok.com/marketing_api/docs?id=1740040177229826) 接口获取受众 ID (`package_id`)。需将 `bind_type` 设置为 `INCLUDE`。 请勿同时传入此字段和 `excluded_pangle_audience_package_ids`。|
##|excluded_pangle_audience_package_ids |string[]| 你希望排除的 Pangle 受众 ID。仅当为 Pangle 广告位时生效。你可以使用 [/pangle_audience_package/get/](https://ads.tiktok.com/marketing_api/docs?id=1740040177229826) 接口获取受众 ID (`package_id`)。需将 `bind_type` 设置为 `EXCLUDE`。请勿同时传入此字段和 `included_pangle_audience_package_ids`。|
##|operating_systems |string[]|你希望定向的设备操作系统。仅允许一个值。 枚举值：`ANDROID`、`IOS`|
##|min_android_version|string|最低 Android 版本。枚举值参见[枚举值 - 最低 Android 版本](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
##|ios14_targeting|string|你希望定向的 iOS 设备。<br><br>枚举值：<ul><li>`UNSET`：运行 iOS 14.4 或更低版本的设备。 </li><li>`IOS14_MINUS`：运行 iOS 14.0 或更低版本的设备，不受 iOS 14 隐私更新的影响。 </li><li>`IOS14_PLUS`：运行 iOS 14.5 或更高版本的设备。此设备组已强制实施 iOS 14 隐私更新。仅专属推广系列支持此值。 </li><li>`ALL`： 运行 iOS 14.5 或更高版本的设备。此设备组已强制实施 iOS 14 隐私更新。此值仅支持商品数据来源为商品库且优化位置为应用的 iOS 应用再营销广告和 iOS 再营销视频购物广告。  </li></ul>|
##|min_ios_version|string|受众最低 iOS 版本。枚举值参见[枚举值 - 最低 iOS 版本](https://ads.tiktok.com/marketing_api/docs?id=1738308662898689)。|
##|ios14_quota_type|string|推广系列是否计入 iOS 14 专属推广系列配额。枚举值：`OCCUPIED`、`UNOCCUPIED`。对于非覆盖和频次推广系列，当 `ios14_targeting` 为 `IOS14_PLUS` 时，此字段自动设置为 `OCCUPIED`。|
##|device_model_ids| string[]| 设备型号 ID 列表。如需详细了解设备型号，参见[设备型号](https://ads.tiktok.com/marketing_api/docs?id=1737172880570369)。|
##|network_types |string[]|你希望定向的网络类型。枚举值参见[枚举值 - 网络类型](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
##|carrier_ids |string[]| 你希望定向的运营商。仅当运营商的 `in_use` 字段为 `true` 时，运营商才生效。如需了解详细信息，参见[获取运营商列表](https://ads.tiktok.com/marketing_api/docs?id=1737168013095938)。 |
##| isp_ids | string[] |定向的互联网服务提供商的 ID。 |
##|device_price_ranges|number[]|定向设备价格范围。10,000 表示 1,000 以上。数字必须为 50 的倍数。<br><b><span style="color: darkred">重要说明</span></b>：系统会在你设置的上限基础上再加 50，并将所得的新数值用作设备定向的实际上限。实际上限会在 TikTok 广告管理平台的广告组设置中显示。如果你设置的价格范围为 [0, 250]，系统实际上会按 [0, 300] 处理。|
##|targeting_expansion{-To be deprecated}| object | 定向拓量设置。<br><br><p><span style="color:darkred"><b>注意</b></span>： 自 2024 年 6 月起，你无法再为广告组启用自动定向或定向拓量功能。为确保 API 集成顺利进行，建议迁移到[智能定向](1783164662979586.html)。 |
###|expansion_enabled|boolean| 是否启用定向拓量。 |
###|expansion_types |string[]| 你希望拓展的目标受众类型。|
##|saved_audience_id|string|当创建广告组时，传入 `saved_audience_id` 后返回。<br>已保存受众 ID。|
##|contextual_tag_ids |string[]|内容标签 ID。如需详细了解如何使用内容相关定向，参见[内容相关定向](https://ads.tiktok.com/marketing_api/docs?id=1745292519923713)  。|
##|brand_safety_type|string|品牌安全类型。枚举值： <ul><li>`NO_BRAND_SAFETY`： 不使用任何品牌安全解决方案。 使用全部库存，意味着你的广告可能会展示在某些成人主题的内容前后。</li><li>`EXPANDED_INVENTORY`：使用 TikTok 品牌安全解决方案。使用扩展库存，意味着你的广告将展示在已移除大部分不当内容、不包含成人主题的内容前后。在下一个 API 版本中，`EXPANDED_INVENTORY` 将替代 `NO_BRAND_SAFETY`，并成为默认的品牌安全选项。 </li><li>`STANDARD_INVENTORY`：使用 TikTok 品牌安全解决方案。使用标准库存，意味着你的广告将展示在适合大多数品牌的内容前后。 </li><li>`LIMITED_INVENTORY`：使用 TikTok 品牌安全解决方案。使用有限库存，意味着你的广告将不会展示在包含成人主题的内容前后。</li><li>`THIRD_PARTY`：使用第三方品牌安全解决方案。</li></ul> 若想获取在你的品牌安全设置下可投放广告的国家和地区，需使用 [/tool/region/](https://ads.tiktok.com/marketing_api/docs?id=1737189539571713) 接口。 <br><p><span style="color:darkred"><b>注意</b></span>： <ul><li> 在竞价广告中，适用于  `APP_PROMOTION`、`WEB_CONVERSIONS`、`TRAFFIC`、`LEAD_GENERATION` 和  `PRODUCT_SALES` 推广目标的出价前第一方品牌安全筛选目前为白名单功能。如需使用此功能，请联系你的 TikTok 销售代表。 </li><li> 出价前第三方品牌安全解决方案目前为白名单功能。如需使用这些功能，请联系你的 TikTok 销售代表。 </li></ul>|
##|brand_safety_partner|string| 品牌安全合作伙伴。仅当 `brand_safety_type` 为 `THIRD_PARTY` 时可用。枚举值：`IAS`、`OPEN_SLATE`（此合作伙伴在 TikTok 广告管理平台上显示为 <strong>DoubleVerify</strong>，因为其已被 DoubleVerify 收购)。<br>若想获取在你的品牌安全设置下可投放广告的国家和地区，需使用 [/tool/region/](https://ads.tiktok.com/marketing_api/docs?id=1737189539571713) 接口。你需要传入品牌安全类型和品牌安全合作伙伴。<br><p><span style="color:darkred"><b>注意</b></span>： <ul><li> 出价前第三方品牌安全解决方案目前为白名单功能。如需使用这些功能，请联系你的 TikTok 销售代表。 </li></ul>|
##|inventory_filter_enabled|boolean|库存筛选（筛选安全视频，隐藏不安全视频），仅当为 `PLACEMENT_TIKTOK` 广告位时生效。可选的值包括：true 表示筛选，false 表示不筛选。 |
##|category_exclusion_ids|string[]|内容排除类别 ID。|
##|vertical_sensitivity_id|string|行业敏感内容类别 ID。  |
##|budget_mode |string|预算模式。如果已启用推广系列预算优化，将返回 `BUDGET_MODE_INFINITE`。如需详细了解预算模式，参见[预算](https://ads.tiktok.com/marketing_api/docs?id=1739381246298114)。|
##|budget |float|广告组预算。<br><br>当启用推广系列预算优化 (`budget_optimize_on`) 时返回 0.0。<br><br>对于 TopView 广告组，此字段表示应用任意折扣后的预估广告组预算。|
##|scheduled_budget|float|预定的次日预算。如果该值不为 0，表示已设置预定预算，且该值即为预算金额；如果该值为 0，表示未设置预定预算。|
##|schedule_type |string|排期类型可为 `SCHEDULE_START_END` 或 `SCHEDULE_FROM_NOW`。如果选择 `SCHEDULE_START_END`，需传入开始时间和结束时间。如果选择 `SCHEDULE_FROM_NOW`，只需传入开始时间。|
##|schedule_start_time |datetime|广告投放开始时间 (UTC+0)，格式为 `YYYY-MM-DD HH:MM:SS`。|
##|schedule_end_time |datetime|广告投放结束时间 (UTC+0)，格式为 `YYYY-MM-DD HH:MM:SS`。|
##| predict_impression | number | 仅当为 TopView 广告时返回。<br><br>预估展示量，以千为单位。<br><br>例如，值为 `1291` 表示预估展示量为 1,291,000。 |
##| topview_reach_range | number[] | 仅当为 TopView 广告时返回。<br><br>预估覆盖人数范围，以千为单位。<br><br>例如，值为 `[342, 456]` 表示预估覆盖人数在 342,000-456,000。<br><br>若想确定预估频次范围，需使用以下公式： <ul><li>频次 = 展示量/覆盖人数</li></ul>例如，如果 `predict_impression` 为 `1291`（代表 1,291,000），`topview_reach_range` 为 `[342, 456]`（代表 342,000-456,000），那么预估频次范围为 2.8-3.8。 |
##| pre_discount_cpm | number | 仅当为 TopView 广告时返回。<br><br>应用任意预算折扣之前的预估千次展示成本 (CPM)。<br><br>示例：11.33。|
##|cpm | number | 仅当为 TopView 广告时返回。<br><br>应用任意预算折扣之后的预估千次展示成本 (CPM)。<br><br>示例：0。|
##|discount_type | string | 仅当为 TopView 广告时返回。<br><br>应用于预算的折扣类型。<br><br>枚举值： <ul><li>`NO_DISCOUNT`：无折扣。</li><li> `BY_PERCENTAGE`：按百分比应用折扣。</li><li>`BY_AMOUNT`：按固定金额应用折扣。 </li></ul>|
##| discount_amount | number | 仅当为 TopView 广告且 `discount_type` 为 `BY_AMOUNT` 时返回。<br><br>预算折扣的固定金额。<br><br>示例：14615.8。|
##|discount_percentage | number | 仅当为 TopView 广告且 `discount_type` 为 `BY_PERCENTAGE` 时返回。<br><br>预算折扣的百分比。 |
##| pre_discount_budget | number | 仅当为 TopView 广告时返回。<br><br>应用折扣前的预算金额。<br><br>示例：14616。 |
##|schedule_infos |object[]| 覆盖和频次广告组的广告投放信息。|
###|schedules |object[]| 广告的按排期投放详细信息。 |
####|start_time |string| 广告投放开始时间。 |
####|end_time |string| 广告投放结束时间。 |
###|expected_orders |number[]| 广告组内某个广告的投放顺序。<br><br>例如，值为 `[1]` 表示该广告将第一个投放。|
###|is_draft |boolean| 广告投放信息是否处于草稿模式。<br><br>如果此字段的值为 `true`，表示在 `schedule_infos` 中定义的广告投放信息尚未与任何特定广告相关联。<br><br>若想将广告投放信息与广告关联，需通过 [/ad/create/](1739953377508354.html) 接口将返回的 `schedule_id` 值传入请求参数 `schedule_id`。将广告投放信息与广告关联后，该字段的值将自动设置为 `false`，`schedule_id` 值将为已与之关联的广告投放信息的广告 ID。 |
###|schedule_id |string| 排期 ID。<br><br>你可以使用 [/ad/create/](1739953377508354.html) 接口，在请求中通过 `schedule_id` 将排期 ID 与广告关联。将 `schedule_id` 与广告关联后，该字段的值将自动设置为已与之关联的广告投放信息的广告 ID，且 `is_draft` 将自动设置为 `false`。  |
##|delivery_mode |string|  在覆盖和频次广告组中，用于排序和排定广告投放的策略。<br><br>枚举值：<ul><li>`STANDARD`：标准投放。你的广告将均匀投放，预计会获得大致相同的访问量。 </li><li>`SCHEDULE`：按排期投放。 设置投放每个广告的特定时间段。 </li><li>`SEQUENCE`：按顺序投放。设置特定的广告投放顺序。 </li><li>`VIEW_OPTIMIZE`：针对播放量优化投放。你的广告将按能最大限度提升完播率 (VTR) 的方式进行投放，系统会将更多展示量分配给预估 VTR 更高的广告。</li><li>`OPTIMIZE`：经过优化的投放，旨在实现最佳广告效果。</li></ul>|
##|dayparting |string|广告投放安排，格式为由 48 x 7 个字符组成的字符串。每个字符都对应星期一到星期日的一个 30 分钟的时间范围。每个字符可设为 0 或 1。 1 表示在该 30 分钟时段投放，0 表示不投放。第一个字符对应星期一 0:01–0:30；第二个字符对应星期一 0:31–1:00；最后一个字符对应星期日 23:31–次日 0:00。<p><span style="color: darkred"><b>注意</b></span><br>不传入、该值全为 0 或全为 1 时，均视为全时投放。 </p>|
##|optimization_goal|string|你希望通过广告实现的可度量成效。枚举值参见[枚举值 - 优化目标](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
##|secondary_optimization_event|string|当 `optimization_goal` 为 `INSTALL` 或 `VALUE` 时的次要目标。枚举值参见[转化事件 - 次要目标事件](https://ads.tiktok.com/marketing_api/docs?id=1739361474981889)。|
##| message_event_set_id | string | 在即时通讯广告组中使用的通讯事件组的 ID。|
##|frequency |number| 频次和 `frequency_schedule` 共同决定用户看到你的广告的频率（仅适用于采用 `REACH` 推广目标的广告）。<br>应同时满足以下条件：<ul><li>1 <= `frequency` <= 1000 </li><li>1 <= `frequency_schedule` <= 30 </li></ul>例如，`frequency` = 2 & `frequency_schedule` = 3 表示“每 3 天展示广告的次数不超过两次”。 |
##|frequency_schedule |number| Frequency_schedule 和 `frequency` 共同决定用户看到你的广告的频率（仅适用于采用 `REACH` 推广目标的广告）。更多信息参见 `frequency` 字段。 |
##|bid_type |string|决定系统的平均成效成本管理方式、预算消耗方式和广告投放方式的出价策略。<br data-tomark-pass>参见[枚举值 - 出价策略](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
##|bid_price |float|出价。你希望达到的平均成效成本（针对成本上限出价策略）。 |
##|conversion_bid_price |float|你可以在此处设置 oCPM（经过优化的千次展示成本）模式下的目标平均转化成本。|
##|deep_bid_type |string|应用内事件的出价策略。枚举值及其描述参见[枚举值 - 深层出价策略](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
##|roas_bid|float|价值优化的 ROAS 目标。|
##| vbo_window | string | 传入的 [VBO IAA](1739381743067137.html)（应用内广告价值优化）或 [VBO IAP](1739381743067137.html)（应用内购买价值优化）的出价策略时间窗口。  <br><br>枚举值： <ul><li>`SEVEN_DAYS`：前 7 天（第 7 天）。  </li><li>`ZERO_DAY`：当天（第 0 天）。 </li></ul>|
##|bid_display_mode|string|计算和度量平均观看成本的方式。  |
##|deep_cpa_bid |float|为应用内事件选择出价策略后，在此字段中传入出价，例如 VO_MIN。|
##|cpv_video_duration |string|优化视频播放时长<br data-tomark-pass>可选的值包括：`SIX_SECONDS`（视频播放 6 秒）和 `TWO_SECONDS`（视频播放 2 秒）|
##|next_day_retention | float | 次日留存率。公式：`next_day_retention` = `conversion_bid_price`/`deep_cpa_bid`。值范围为 (0,1]。仅当 `placements` 为 `PLACEMENT_PANGLE` 且 `secondary_optimization_event` 为 `NEXT_DAY_OPEN` 时生效。 |
##| click_attribution_window | string | 广告组的点击归因窗口期。此归因窗口期指用户从点击广告到采取行动之间的时间间隔。<br><br>枚举值： <ul><li>`OFF`：关闭。 </li><li> `ONE_DAY`：1 天点击归因窗口期。</li><li>`SEVEN_DAYS`：7 天点击归因窗口期。 </li><li>`FOURTEEN_DAYS`：14 天点击归因窗口期。</li><li> `TWENTY_EIGHT_DAYS`：28 天点击归因窗口期。 </li></ul>|
##| engaged_view_attribution_window | string | 广告组的深度互动观看归因窗口期。此归因窗口期指用户观看你的视频广告至少 6 秒后，在多长时间范围内的转化会被计入。<br><br>枚举值： <ul><li>`ONE_DAY`：1 天深度互动观看归因窗口期。</li><li>`SEVEN_DAYS`：7 天深度互动观看归因窗口期。</li></ul>|
##| view_attribution_window | string | 广告组的观看归因窗口期。此归因窗口期指用户从观看广告到采取行动之间的时间间隔。<br><br>枚举值： <ul><li>`OFF`：关闭。</li><li>`ONE_DAY`：1 天观看归因窗口期。</li><li>`SEVEN_DAYS`：7 天观看归因窗口期。</li></ul>|
##| attribution_event_count | string | 广告组的事件数量（统计类型）。<br>在用户仅浏览或点击广告后，对其操作次数的统计方式。<br><br>枚举值： <ul><li>`UNSET`：未设置。 </li><li> `EVERY`：每一次。将某人的多个事件分别统计成不同的转化次数。 </li><li> `ONCE`：仅一次。将某人的多个事件计为 1 次转化。</li></ul>|
##|billing_event |string| 计费事件。<br>枚举值参见[枚举值 - 计费事件](https://business-api.tiktok.com/portal/docs?id=1737174886619138#item-link-Billing%20Event)。|
##|pacing |string| 你可以在 `PACING_MODE_SMOOTH` 和 `PACING_MODE_FAST` 之间进行选择。如果选择 `PACING_MODE_SMOOTH`，预算将在排期内均匀分配。如果选择 `PACING_MODE_FAST`，将尽快消耗预算并产生成效。如果启用推广系列预算优化 (`budget_optimize_on`)，你的设置将被忽略并设置为 `PACING_MODE_SMOOTH`。否则，此为必填字段。 |
##|operation_status |string|操作状态。<br><br>枚举值：<ul><li>`ENABLE`：广告组已启用（处于“开启”状态）。</li><li>`DISABLE`：广告组未启用（处于“关闭”状态）。 </li><li>`FROZEN`：广告组已终止，无法启用。</li></ul> |
##|secondary_status |string|广告组状态（二级状态）。枚举值参见[枚举值 - 广告组状态 - 二级状态](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。 <br><p><span style="color:darkred"><b>注意</b></span>：在沙箱环境中不会返回此字段，因为广告组实际未投放。|
##|statistic_type |string| 转化出价统计类型，出价方式为 `EVERYTIME`（每次付费）/`NONE`（去重付费）|
##|is_hfss |boolean|是否推广 HFSS（高脂、高盐、高糖）产品/品牌内容。<br><br>支持的值：`true`、`false`。 |
##| is_lhf_compliance | boolean | 推广内容是否符合 LHF（较不健康食品）合规要求。<br><br>当 `is_lhf_compliance` 为 `true` 时，即表示你确认，你在英国 TikTok 上推广的任何食品或饮料均符合 [2024 年较不健康食品法规](https://www.legislation.gov.uk/uksi/2024/1266/made)以及其他所有适用法律。<br><br>支持的值：`true`、`false`。 |
##|creative_material_mode |string|创意的投放策略。<br><br>枚举值：`CUSTOM`（自定义）、`DYNAMIC`（程序化创意）和 `SMART_CREATIVE`（智能创意）。<br><br>对于升级版 Smart+ 广告组，此字段将为空。|
##|adgroup_app_profile_page_state|string| 表示广告组是否使用应用介绍页。枚举值：`INVALID`、`UNSET`、`ON`、`OFF`。|
##|feed_type |string| 信息流类型选项。枚举值：`STANDARD_FEED`、`TOP_FEED`。  |
##| rf_purchased_type  | string | 覆盖和频次广告组的计费方式。如需了解更多详细信息，参见[枚举值 - 覆盖和频次购买类型](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。 <br><p><span style="color:darkred"><b>注意</b></span>：对于非覆盖和频次广告，此字段的值将始终为空。|
##| purchased_impression | number | 要购买的展示量。 <br><p><span style="color:darkred"><b>注意</b></span>：对于非覆盖和频次广告，此字段的值将始终为空。|
##| purchased_reach  | number | 已购买的用户覆盖人数。 <br><p><span style="color:darkred"><b>注意</b></span>：对于非覆盖和频次广告，此字段的值将始终为空。 |
##| rf_estimated_cpr | number |  预估千次覆盖成本。 <br><p><span style="color:darkred"><b>注意</b></span>：对于非覆盖和频次广告，此字段的值将始终为空。|
##| rf_estimated_frequency | number | 预估的展示频次。 <br><p><span style="color:darkred"><b>注意</b></span>：对于非覆盖和频次广告，此字段的值将始终为空。|
##| split_test_group_id | string | 拆分对比测试组 ID。当广告组属于拆分对比测试的一部分时返回。 |
##| split_test_status | string | 拆分对比测试状态。当广告组属于拆分对比测试的一部分时返回。 |
##|is_new_structure|boolean|推广系列是否使用新结构 |
##|skip_learning_phase |boolean|是否跳过学习阶段。|
##|conversion_window（已弃用） |string| 你希望用户点击或观看你的广告后达成转化的时间范围。系统将根据你选择的时间范围内的转化数据优化广告投放。此设置不会影响你的归因数据。枚举值参见[枚举值 - 转化窗口期](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
#|page_info |object|分页信息 |
##|page |number|当前页码 |
##|page_size |number|分页大小 |
##|total_number |number|总数，符合条件的广告组总数 |
##|total_page |number|总页数 |

示例

(code curl http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "list": [
            {
                "budget_mode": "BUDGET_MODE_TOTAL",
                "included_custom_actions": [],
                "delivery_mode": null,
                "auto_targeting_enabled": false,
                "app_download_url": null,
                "placements": [
                    "PLACEMENT_TIKTOK"
                ],
                "pixel_id": null,
                "conversion_window": null,
                "schedule_type": "SCHEDULE_START_END",
                "brand_safety_partner": null,
                "interest_category_ids": [],
                "adgroup_id": "{{adgroup_id}}",
                "campaign_name": "{{campaign_name}}",
                "schedule_infos": null,
                "share_disabled": false,
                "brand_safety_type": "NO_BRAND_SAFETY",
                "campaign_id": "{{campaign_id}}",
                "ios14_quota_type": "UNOCCUPIED",
                "network_types": [],
                "app_type": null,
                "bid_type": "BID_TYPE_NO_BID",
                "conversion_bid_price": 0,
                "optimization_goal": "CLICK",
                "deep_bid_type": null,
                "video_download_disabled": false,
                "schedule_end_time": "{{schedule_end_time}}",
                "scheduled_budget": 0,
                "is_hfss": false,
                "frequency": null,
                "bid_price": 0,
                "actions": [],
                "deep_cpa_bid": 0,
                "adgroup_name": "{{adgroup_name}}",
                "category_id": "0",
                "purchased_impression": null,
                "budget": {{budget}},
                "app_id": null,
                "promotion_type": "WEBSITE",
                "age_groups": null,
                "next_day_retention": null,
                "pacing": "PACING_MODE_SMOOTH",
                "device_price_ranges": null,
                "location_ids": [
                    "{{location_id}}"
                ],
                "secondary_status": "ADGROUP_STATUS_CREATE",
                "billing_event": "CPC",
                "advertiser_id": "{{advertiser_id}}",
                "create_time": "{{create_time}}",
                "operation_status": "ENABLE",
                "placement_type": "PLACEMENT_TYPE_NORMAL",
                "optimization_event": null,
                "audience_ids": [],
                "secondary_optimization_event": null,
                "excluded_custom_actions": [],
                "languages": [],
                "modify_time": "{{modify_time}}",
                "excluded_audience_ids": [],
                "rf_estimated_cpr": null,
                "skip_learning_phase": false,
                "operating_systems": [
                    "ANDROID"
                ],
                "creative_material_mode": "CUSTOM",
                "search_result_enabled": false,
                "rf_purchased_type": null,
                "inventory_filter_enabled": false,
                "adgroup_app_profile_page_state": null,
                "rf_estimated_frequency": null,
                "gender": "GENDER_UNLIMITED",
                "statistic_type": null,
                "purchased_reach": null,
                "is_new_structure": true,
                "interest_keyword_ids": [],
                "bid_display_mode": "CPMV",
                "dayparting": "111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111",
                "keywords": null,
                "schedule_start_time": "{{schedule_start_time}}",
                "comment_disabled": false,
                "frequency_schedule": null,
                "feed_type": null
            },
            {
                "budget_mode": "BUDGET_MODE_TOTAL",
                "included_custom_actions": [],
                "delivery_mode": null,
                "auto_targeting_enabled": false,
                "app_download_url": null,
                "placements": [
                    "PLACEMENT_TIKTOK"
                ],
                "pixel_id": null,
                "conversion_window": null,
                "schedule_type": "SCHEDULE_START_END",
                "brand_safety_partner": null,
                "interest_category_ids": [],
                "adgroup_id": "{{adgroup_id}}",
                "campaign_name": "{{campaign_name}}",
                "schedule_infos": null,
                "share_disabled": false,
                "brand_safety_type": "NO_BRAND_SAFETY",
                "campaign_id": "{{campaign_id}}",
                "ios14_quota_type": "UNOCCUPIED",
                "network_types": [],
                "app_type": null,
                "bid_type": "BID_TYPE_NO_BID",
                "conversion_bid_price": 0,
                "optimization_goal": "CLICK",
                "deep_bid_type": null,
                "video_download_disabled": false,
                "schedule_end_time": "{{schedule_end_time}}",
                "scheduled_budget": 0,
                "is_hfss": false,
                "frequency": null,
                "bid_price": 0,
                "actions": [],
                "deep_cpa_bid": 0,
                "adgroup_name": "{{adgroup_name}}",
                "category_id": "0",
                "purchased_impression": null,
                "budget": {{budget}},
                "app_id": null,
                "promotion_type": "WEBSITE",
                "age_groups": null,
                "next_day_retention": null,
                "pacing": "PACING_MODE_SMOOTH",
                "device_price_ranges": null,
                "location_ids": [
                    "{{location_id}}"
                ],
                "secondary_status": "ADGROUP_STATUS_CREATE",
                "billing_event": "CPC",
                "advertiser_id": "{{advertiser_id}}",
                "create_time": "{{create_time}}",
                "operation_status": "ENABLE",
                "placement_type": "PLACEMENT_TYPE_NORMAL",
                "optimization_event": null,
                "audience_ids": [],
                "secondary_optimization_event": null,
                "excluded_custom_actions": [],
                "languages": [],
                "modify_time": "{{modify_time}}",
                "excluded_audience_ids": [],
                "rf_estimated_cpr": null,
                "skip_learning_phase": false,
                "operating_systems": [
                    "ANDROID"
                ],
                "creative_material_mode": "CUSTOM",
                "search_result_enabled": false,
                "rf_purchased_type": null,
                "inventory_filter_enabled": false,
                "adgroup_app_profile_page_state": null,
                "rf_estimated_frequency": null,
                "gender": "GENDER_UNLIMITED",
                "statistic_type": null,
                "purchased_reach": null,
                "is_new_structure": true,
                "interest_keyword_ids": [],
                "bid_display_mode": "CPMV",
                "dayparting": "111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111",
                "keywords": null,
                "schedule_start_time": "{{schedule_start_time}}",
                "comment_disabled": false,
                "frequency_schedule": null,
                "feed_type": null
            }
        ],
        "page_info": {
            "page": 1,
            "page_size": 10,
            "total_page": 1,
            "total_number": 2
        }
    }
}
(/code)
← 预估受众人数创建广告组 →

内容来源：TikTok API for Business 官方文档 · 本地归档

在接这个接口时卡住了？
Stuck wiring this API into production? We build ad-delivery tooling on these platforms — campaign automation, reporting pipelines, error-handling and migration between API versions.
联系我们 · Talk to us 每日平台更新简报 →