获取升级版 Smart+ 广告组
此接口可用于获取广告账号内的升级版 Smart+ 广告组。
请求
地址 https://business-api.tiktok.com/open_api/v1.3/smart_plus/adgroup/get/
方法 GET
Header
|字段{35%}|类型{15%}|描述{50%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](1738373164380162.html)接口获取。|
参数
|字段{35%}|类型{15%}|描述{50%}|
|--- |--- |--- |
| advertiser_id {必填} | string | 广告主 ID。 |
| fields | string[] | 要获取的字段。<br><br>如果未指定该字段，那么默认返回所有字段。<br><br>如需了解允许的字段，参见<a href="#item-link-Response">返回</a>小节中 `list` 下的字段。|
| filtering | object | 筛选条件。<br><br>示例：`filtering={"objective_type":"APP_PROMOTION"}`|
#|campaign_ids | string[] | 按推广系列 ID 筛选。<br><br>最大数量：100。<br><br>若想获取推广系列 ID，需使用 [/smart_plus/campaign/get/](1843312818332930.html) 接口。 |
#|adgroup_ids | string[] | 按广告组 ID 筛选。<br><br>最大数量：100。 |
#|adgroup_name | string | 广告组名称。 |
#|primary_status | string | 一级状态。<br><br>枚举值参见[枚举值 - 一级状态](https://business-api.tiktok.com/portal/docs?id=1737174886619138#item-link-Primary%20Status)。<br>默认值为 `STATUS_NOT_DELETE`，会返回除 `STATUS_DELETE` 之外所有状态的广告组。<br><br>如果希望获取包括 `STATUS_DELETE` 在内的所有状态的广告组，需使用 `STATUS_ALL`。 |
#|secondary_status | string | 广告组二级状态。<br><br>枚举值参见[枚举值 - 广告组状态 - 二级状态](https://business-api.tiktok.com/portal/docs?id=1737174886619138#item-link-Ad%20group%20status%20-%20secondary%20status)。 |
#|objective_type | string | 推广目标。<br><br>目前，我们支持 `APP_PROMOTION`、`WEB_CONVERSIONS` 和 `LEAD_GENERATION`。<br><br>如需详细了解枚举值，参见[枚举值 - 推广目标](https://business-api.tiktok.com/portal/docs?id=1737174886619138#item-link-Advertising%20Objective)。 |
#| sales_destination | string | 销售目标页面，即你希望提升销量的目标页面。<br><br>枚举值：<ul><li>`WEBSITE`：网站。提升你的网站上的销量。</li><li>`APP`：应用。提升你的应用上的销量（需要商品库）。</li><li>`WEB_AND_APP`：网站和应用。提升你的网站和应用上的销量。</li></ul>|
#|promotion_type|string|推广类型（优化位置）。你可以使用此字段来选择商品的投放位置。<br><br>目前，我们支持 `APP_ANDROID`、`APP_IOS`、`WEBSITE`、`MINI_GAME`、`NATIVE_SERIES` 和 `LEAD_GENERATION`。<ul><li>当 `objective_type` 为 `APP_PROMOTION` 且 `app_promotion_type` 为 `APP_INSTAL` 时，此字段将为 `APP_ANDROID` 或 `APP_IOS`。</li><li>当 `objective_type` 为 `APP_PROMOTION` 且 `app_promotion_type` 为 `MINIS` 时，此字段将为 `MINI_APP`、`MINI_GAME` 或 `NATIVE_SERIES`。</li><li>当 `objective_type` 为 `WEB_CONVERSIONS` 时：<ul><li>如果 `sales_destination` 为 `WEBSITE`，此字段将为 `WEBSITE`。</li><li>如果 `sales_destination` 为 `APP`，此字段将为 `APP_ANDROID` 或 `APP_IOS`。</li></ul></li><li>当 `objective_type` 为 `LEAD_GENERATION` 时，此字段将为以下任意值：<ul><li>`LEAD_GENERATION`</li><li>`LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE`</li><li>`LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE`</li><li>`LEAD_GEN_CLICK_TO_CALL`</li></ul></li></ul>|
#|optimization_goal | string | 你希望通过推广系列实现的可度量成效。<br><br>目前，我们支持 `CLICK`、`INSTALL`、`IN_APP_EVENT`、`VALUE`、`CONVERT`、`TRAFFIC_LANDING_PAGE_VIEW` 和 `LEAD_GENERATION`。<br><br>如需查找关于每个优化目标的详细描述，参见[枚举值 - 优化目标](https://business-api.tiktok.com/portal/docs?id=1737174886619138#item-link-Optimization%20Goal)。 |
| page | number | 当前页码。<br><br>默认值：1。<br>值范围：≥ 1。 |
| page_size | number | 分页大小。<br><br>默认值：10。<br>值范围：1-1,000。 |
示例
(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/smart_plus/adgroup/get/?advertiser_id={{advertiser_id}}&page=1&page_size=1000' \
--header 'Access-Token: {{Access-Token}}'
(/code)
返回
|字段{35%}|类型{15%}|描述{50%}|
|---|---|---|
|code |number|返回码。完整返回码列表及描述参见[附录 - 返回码](1737172488964097.html)。 |
|message|string|返回信息。更多信息参见[附录 - 返回码](1737172488964097.html)。|
|request_id |string|请求的日志 ID，唯一标识一个请求。 |
|data |object|返回数据。|
#|list |object[]|广告账号中升级版 Smart+ 广告组的列表。|
##|advertiser_id |string|广告主 ID。|
##|campaign_id |string|推广系列 ID。|
##|campaign_name |string|广告组所属的推广系列的名称。|
##|adgroup_id |string|广告组 ID。|
##|adgroup_name |string|广告组名称。|
##|catalog_id |string|当推广系列层级的 `catalog_enabled` 为 `true` 时返回。<br><br>用于广告组的商品库的 ID。|
##|catalog_authorized_bc_id |string|当推广系列层级的 `catalog_enabled` 为 `true` 时返回。<br><br>商品库 (`catalog_id`) 所属的商务中心的 ID。|
##|promotion_type |string|推广类型（优化位置）。你可以使用此字段来选择商品的投放位置。<br><br>目前，我们支持 `APP_ANDROID`、`APP_IOS`、`WEBSITE`、`MINI_GAME`、`NATIVE_SERIES` 和 `LEAD_GENERATION`。<ul><li>当 `objective_type` 为 `APP_PROMOTION` 且 `app_promotion_type` 为 `APP_INSTAL` 时，此字段将为 `APP_ANDROID` 或 `APP_IOS`。</li><li>当 `objective_type` 为 `APP_PROMOTION` 且 `app_promotion_type` 为 `MINIS` 时，此字段将为 `MINI_APP`、`MINI_GAME` 或 `NATIVE_SERIES`。</li><li>当 `objective_type` 为 `WEB_CONVERSIONS` 时：<ul><li>如果 `sales_destination` 为 `WEBSITE`，此字段将为 `WEBSITE`。</li><li>如果 `sales_destination` 为 `APP`，此字段将为 `APP_ANDROID` 或 `APP_IOS`。</li></ul></li><li>当 `objective_type` 为 `LEAD_GENERATION` 时，此字段将为以下任意值：<ul><li>`LEAD_GENERATION`</li><li>`LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE`</li><li>`LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE`</li><li>`LEAD_GEN_CLICK_TO_CALL`</li></ul></li></ul>|
##|app_id |string|待推广应用的 ID。<br><br>若想获取应用 ID 列表，需使用 [/app/list/](1740859313270786.html) 接口。|
##| gaming_ad_compliance_agreement|string|仅在以下任意场景中返回：<ul><li>场景 1：当在推广系列层级同时满足以下两个条件时：<ul><li>`objective_type` 为 `APP_PROMOTION`。</li><li>`app_promotion_type` 为 `APP_RETARGETING`。</li></ul></li><li>场景 2：当在推广系列层级同时满足以下所有条件时：<ul><li>`objective_type` 为 `APP_PROMOTION`。</li><li>`app_promotion_type` 为 `APP_INSTALL`。</li><li>`campaign_type` 为 `REGULAR_CAMPAIGN`。</li></ul></li></ul><br>是否同意 TikTok 游戏广告主合规保证政策。<br><br>政策如下：你确认并证明，你希望在 TikTok 上推广的任何游戏应用、产品或服务（游戏），包括任何相关的 URL，均 (a) 符合可访问或玩该游戏的司法管辖区的所有适用法律和法规，并且可以根据要求提供支持文件来证明该游戏不属于非法赌博或博彩；以及 (b) 过去和现在均未经受任何关于该游戏的合法性或合规性的调查或诉讼。<br><br>枚举值：<ul><li>`ON`：同意该政策。</li><li>`OFF`：不接受该政策。</li></ul>|
##|promotion_website_type |string|TikTok 即时体验页面类型。<br><br>目前，我们仅支持 `TIKTOK_NATIVE_PAGE`（使用 TikTok 即时体验页面）。|
##|promotion_type|string|推广类型（优化位置）。你可以使用此字段来选择商品的投放位置。<br><br>目前，我们支持 `APP_ANDROID`、`APP_IOS`、`WEBSITE`、`MINI_GAME` 和 `LEAD_GENERATION`。<ul><li>当 `objective_type` 为 `APP_PROMOTION` 且 `app_promotion_type` 为 `APP_INSTAL` 时，此字段将为 `APP_ANDROID` 或 `APP_IOS`。</li><li>当 `objective_type` 为 `APP_PROMOTION` 且 `app_promotion_type` 为 `MINIS` 时，此字段将为 `MINI_APP` 或 `MINI_GAME`。</li><li>当 `objective_type` 为 `WEB_CONVERSIONS` 时：<ul><li>如果 `sales_destination` 为 `WEBSITE`，此字段将为 `WEBSITE`。</li><li>如果 `sales_destination` 为 `APP`，此字段将为 `APP_ANDROID` 或 `APP_IOS`。</li></ul></li><li>当 `objective_type` 为 `LEAD_GENERATION` 时，此字段将为以下任意值：<ul><li>`LEAD_GENERATION`</li><li>`LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE`</li><li>`LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE`</li><li>`LEAD_GEN_CLICK_TO_CALL`</li></ul></li></ul>|
##|optimization_goal |string|你希望通过广告实现的可度量成效。<br><br>枚举值参见[枚举值 - 优化目标](https://business-api.tiktok.com/portal/docs?id=1737174886619138#item-link-Optimization%20Goal)。|
##|pixel_id |string|Pixel ID。|
##| app_config | object[] | 当 `sales_destination` 为 `WEB_AND_APP` 时返回。<br><br>待推广的一个或多个应用的详细信息。 |
###| app_id | string | 待推广应用的 ID。 |
##| minis_id|string|当 `promotion_type` 为 `MINI_APP` 或 `MINI_GAME` 时返回。<br><br>TikTok Mini 的 ID。|
##|optimization_event |string|广告组的转化事件。<br><br>更多信息参见[转化事件](1739361474981889.html)。<br><br><p><span style="color:darkred"><b>注意</b></span>：如果在创建广告组时将 `optimization_event` 设置为 `IMPRESSION_LEVEL_AD_REVENUE` 或 `AD_REVENUE_VALUE`（请注意，这两个枚举值相同且效果完全一致）以启用价值优化，返回的 `optimization_event` 将始终为 `IMPRESSION_LEVEL_AD_REVENUE`。|
##|custom_conversion_id |string|用于广告组的自定义转化的 ID。|
##|deep_funnel_optimization_status |string|通过深层漏斗优化，你可以在主要优化事件之外再选择一个次要事件，这有助于提升推广系列的效果。 <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。<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`。|
##|app_attribution_source|string|你的应用的归因来源。<br><br>你选择的归因来源将用于优化、出价和报告。<br><br>枚举值：<ul><li>`MMP`: MMP 归因。来自所选 MMP 的信号将用于归因。</li><li>`SAN`: SAN 归因。来自 TikTok 自归因网络的信号将用于归因。</li></ul>|
##|app_data_source|string|你的应用的数据源。<br><br>你选择的归因信号将用于报告。<br><br>枚举值：<ul><li>`MMP`: MMP 信号。来自你的 MMP 的信号将用于报告。</li><li>`EVENT_SDK`: 应用事件 SDK 信号。来自 TikTok 应用事件 SDK 的信号将用于报告。</li><li>`EVENT_API`: 事件 API 信号。来自 TikTok 事件 API 的信号将用于报告。</li></ul>|
##| identity_id|string|仅在以下任意场景中返回： <ul><li>场景 1：当 `promotion_type` 为 `NATIVE_SERIES` 时。</li><li>场景 2：当 `promotion_type` 为 `LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE`，并且你的广告账号已加入白名单，可以在 TikTok 私信广告的广告组层级选择 TikTok 账号。</li></ul><br>广告发布身份 ID。 |
##| identity_type |string|仅在以下任意场景中返回： <ul><li>场景 1：当 `promotion_type` 为 `NATIVE_SERIES` 时。</li><li>场景 2：当 `promotion_type` 为 `LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE`，并且你的广告账号已加入白名单，可以在 TikTok 私信广告的广告组层级选择 TikTok 账号。</li></ul><br>广告发布身份类型。<br><br>枚举值： <ul><li>`TT_USER`：TikTok 企业号用户。</li><li>`BC_AUTH_TT`：商务中心有权访问的 TikTok 账号。</li></ul><br>详细信息参见[认证身份](1738958351620097.html)。|
##| identity_authorized_bc_id|string|当 `identity_type` 为 `BC_AUTH_TT` 时返回。<br><br>与“添加到商务中心的 TikTok 用户”类型广告发布身份关联的商务中心 ID。|
##|native_series_id | string | TikTok 剧集 ID。<br>剧集提供由创作者制作的独家优质视频合集。用户可通过创作者主页或 TikTok 视频所附链接购买并观看剧集。 |
##| 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><br>如需详细了解如何创建升级版 Smart+ TikTok 即时通讯广告，参见[创建以即时通讯应用作为优化位置的升级版 Smart+ 线索收集推广系列](1847302988449921.html)。|
##| zalo_id_type |string|Zalo 联系人格式的类型。<br><br>枚举值：<ul><li>`ZALO_OFFICIAL_ACCOUNT`：Zalo 官方账号 ID。 </li><li>`ZALO_PHONE_ACCOUNT`：Zalo 电话号码。 </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>当 `zalo_id_type` 为 `ZALO_OFFICIAL_ACCOUNT` 时，此字段表示 Zalo 官方账号 ID。</li><li>当 `messaging_app_type` 为 `WHATSAPP` 或 `zalo_id_type` 为 `ZALO_PHONE_ACCOUNT`时，此字段表示根据传入的 `phone_info` 自动填充的 WhatsApp 或 Zalo 电话号码。</li></ul>|
##| message_event_set_id|string|要在即时通讯广告组中使用的通讯事件组的 ID。<br><br>如果广告组设置中的即时通讯应用账号（无论是通过 `messaging_app_account_id` 传入的 Messenger 账号、Zalo 官方账号，还是与传入的 `phone_info` 匹配的 WhatsApp 或 Zalo 电话账号）与现有事件组匹配，此字段将<b>自动填充</b>与你选择的即时通讯应用账号关联的去重通讯事件组。|
##| phone_info|object|WhatsApp 或 Zalo 电话号码的详细信息。|
###| phone_region_code |string|WhatsApp 电话号码或 Zalo 电话号码的地区代码。<br><br>示例：`US`。|
###| phone_region_calling_code|string|WhatsApp 电话号码或 Zalo 电话号码的国际区号。<br><br>示例：`+1`。|
###| phone_number|string|WhatsApp 电话号码或 Zalo 电话号码。|
##|bid_type |string|出价策略。<br><br>枚举值及其描述参见[枚举值 - 出价策略](https://business-api.tiktok.com/portal/docs?id=1737174886619138#item-link-Bidding%20Strategy)。|
##|bid_price |float|目标平均点击成本。系统会在保持平均成效成本接近或低于指定金额的同时，尽可能获得更多成效。|
##|conversion_bid_price |float|目标平均转化成本或落地页浏览平均成本。系统会在保持平均成效成本接近或低于指定金额的同时，尽可能获得更多成效。|
##|deep_bid_type |string|应用内事件的出价策略。<br><br>枚举值及其描述参见[枚举值 - 深层事件出价策略](https://business-api.tiktok.com/portal/docs?id=1737174886619138#item-link-Deep%20Event%20Bidding%20Strategy)。|
##|roas_bid |float|价值优化的目标 ROAS。|
##| incentive_offer_type|string|适用于升级版 Smart+ 广告组的激励赠款类型。<br>如果你的广告组符合资格条件，并超过特定的 CPA 或最低 ROAS/目标 ROAS 阈值，你将获得激励性质的广告赠款，可供你在同一广告账号中使用。<br>如需详细了解获得激励赠款的资格条件以及激励金额的计算方法，参见 [Smart+ 平台激励赠款活动（成本上限/最低 ROAS/目标 ROAS）](https://ads.tiktok.com/help/article/incentive-offer)。<br><br>枚举值：<ul><li>`INELIGIBLE`：此广告组不符合获得任何激励赠款的条件。</li><li>`COST_CAP_AND_MIN_ROAS`：此广告组使用成本上限或最低 ROAS/目标 ROAS 出价策略，并有资格获得激励赠款。 </li></ul>|
##|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>|
##|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><li>`THIRTY_DAYS`：30 天点击归因窗口期。</li><li>`THIRTY_TWO_DAYS`：32 天点击归因窗口期。</li><li>`ONE_HUNDRED_EIGHTY_DAYS`：180 天点击归因窗口期。</li></ul>|
##| engaged_view_attribution_window | string | 深度互动观看归因窗口期。此归因窗口期指用户观看你的视频广告至少 6 秒后，在多长时间范围内的转化会被计入。<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>|
##|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><br>枚举值参见[枚举值 - 计费事件](https://business-api.tiktok.com/portal/docs?id=1737174886619138#item-link-Billing%20Event)。|
##|pacing |string|投放速度。你选择的广告投放速度决定了日预算的使用速度。<br><br>枚举值：<ul><li>`PACING_MODE_SMOOTH`：标准。根据市场需求和高峰时段价格，尽可能均匀地使用预算。此投放速度适合偏好稳定消耗的广告主。</li></ul>|
##|budget_mode |string|广告组预算模式。<br><br>枚举值：<ul><li>`BUDGET_MODE_TOTAL`：总预算。</li><li>`BUDGET_MODE_DYNAMIC_DAILY_BUDGET`：动态日预算。即一周内的平均日预算。日消耗不会超过平均日预算的 125%。周消耗不会超过平均日预算的 7 倍。*</li></ul>|
##| budget_auto_adjust_strategy |string|当同时满足以下两个条件时返回：<ul><li>在推广系列层级：`budget_optimize_on` 为 `false`。</li><li>在广告组层级：`budget_mode` 为 `BUDGET_MODE_DYNAMIC_DAILY_BUDGET`。</li></ul><br>自定义广告组预算的广告组预算策略。<br><br>枚举值： <ul><li>`AUTO_BUDGET_INCREASE`：启用基于目标增加预算功能。允许系统在广告效果出色且满足目标 CPA、第 0 天目标 ROAS 和预算要求时自动增加预算。 </li><li>当 `budget_auto_adjust_strategy` 为 `AUTO_BUDGET_INCREASE` 时，传入的 `budget` 将作为初始日预算。如果你的预算利用率至少达到 90%，日预算将自动增加 20%，每天最多可增加 10 次。你的日预算将在每天重置为原来的日预算。</li><li>`UNSET`：禁用基于目标增加预算功能。</li></ul>|
##|budget|float|固定广告组预算或初始广告组预算。<ul><li>当 `budget_auto_adjust_strategy` 为 `UNSET` 时，此字段表示固定广告组预算。</li><li>当 `budget_auto_adjust_strategy` 为 `AUTO_BUDGET_INCREASE` 时，此字段表示初始广告组预算。若想获取当前的推广系列预算，请查看返回的 `current_budget`。</li></ul>|
##| current_budget|float|仅当 `budget_auto_adjust_strategy` 为 `AUTO_BUDGET_INCREASE` 时返回。<br><br>已启用基于目标增加预算功能的广告组的当前预算。|
##|min_budget |float|广告组最低预算。<br>系统会尽量确保消耗至少达到该金额，但不作保证。|
##|schedule_type |string|排期类型。<br><br>枚举值：<ul><li>`SCHEDULE_FROM_NOW`：从排定的开始时间起持续投放广告组。</li><li>`SCHEDULE_START_END`：在排定的开始时间和结束时间之间投放广告组。</li></ul>|
##|schedule_start_time |string|广告组投放开始时间 ，格式为 `YYYY-MM-DD HH:MM:SS` (UTC+0)。|
##|schedule_end_time |string|广告组投放结束时间 ，格式为 `YYYY-MM-DD HH:MM:SS` (UTC+0)。|
##| movie_premiere_date|string|院线上映日期，格式为 `YYYY-MM-DD` (UTC+0)。<br><br>提供电影上映日期，供系统将该时间纳入效果优化中。|
##|dayparting |string|广告投放安排，格式为由 48 x 7 个字符组成的字符串。<br>每个字符都对应星期一到星期日的一个 30 分钟的时间范围。每个字符可设为 0 或 1。1 表示在该 30 分钟时段投放，0 表示不投放。第一个字符对应星期一 0:01–0:30；第二个字符对应星期一 0:31–1:00；最后一个字符对应星期日 23:31–次日 0:00。<br><br><p><span style="color:darkred"><b>注意</b></span>：当该值全为 0 或全为 1 时，均视为全时投放。</p>|
##|targeting_optimization_mode |string|受众定向优化模式。<br><br>枚举值：<ul><li>`MANUAL`：自定义定向。你可以利用自定义定向设置，精准控制广告的目标受众。这可能会限制广告投放并影响推广效果。</li><li>`AUTOMATIC`：自动定向。你可以使用自动定向来充分利用实时数据和机器学习，向最有可能与广告互动的受众定向投放广告。</li></ul>|
##|suggestion_audience_enabled |boolean|是否启用受众建议。<br>受众建议通过指定额外的受众设置来指导自动定向。这些仅为建议，不能保证广告一定会投放给这些受众。<br><br>支持的值：`true`、`false`。|
##|targeting_spec |object|定向设置。|
###| app_targeting_type |string|仅当同时满足以下所有条件时返回：<ul><li>在推广系列层级：</li><li>`objective_type` 为 `WEB_CONVERSIONS`</li><li>`sales_destination` 为 `APP`。</li><li>`optimization_goal` 为 `CLICK`、`IN_APP_EVENT` 或 `VALUE`。</li></ul><br>应用定向类型。<br><br>枚举值：<ul><li>`PROSPECT`：潜客开发。寻找潜在顾客，包括尚未与你的商品互动过的用户。</li><li>`RETARGETING`：再营销。向在 TikTok 内外与你的企业互动过的用户展示广告。</li></ul>|
###|location_ids |string[]|你希望定向的地域的 ID。|
###|zipcode_ids |string[]|定向地域的邮政编码 ID。|
###|spc_audience_age |string|广告组定向的年龄组。<br><br>枚举值：<ul><li>`ALL`：所有年龄组。</li><li>`OVER_EIGHTEEN`：18 岁以上。</li><li>`OVER_TWENTY_FIVE`：25 岁以上。</li></ul>|
###|languages |string[]|你希望定向的语言的代码。<br>支持的语言代码列表参见[枚举值 - 语言代码](https://business-api.tiktok.com/portal/docs?id=1737174886619138#item-link-Language%20Code)。|
###|operating_systems |string[]|你希望定向的设备操作系统。<br><br>枚举值：`ANDROID`、`IOS`|
###|excluded_audience_ids |string[]|要排除的受众 ID 列表。|
###|age_groups |string[]|你希望定向的年龄组。<br><br>枚举值参见[枚举值 - 受众年龄区间](https://business-api.tiktok.com/portal/docs?id=1737174886619138#item-link-Age%20Group)。|
###|gender |string|你希望定向的性别。<br><br>枚举值：`GENDER_FEMALE`、`GENDER_MALE`、`GENDER_UNLIMITED`。|
###|audience_ids |string[]|受众 ID 列表。|
###|shopping_ads_retargeting_type|string|再营销类型。<br><br>枚举值：<ul><li>`LAB1`：对已浏览商品或将商品加入购物车但未购买的受众进行再营销。</li><li>`LAB2`：对已将商品加入购物车但未购买的受众进行再营销。</li><li>`LAB3`：使用自定义组合对受众进行再营销。</li><li>`OFF`：不进行再营销。</li></ul>|
###|shopping_ads_retargeting_actions_days|number|当 `shopping_ads_retargeting_type` 为 `LAB1` 或 `LAB2` 时返回。<br><br>所传入受众操作的合法时间范围。系统将对在此时间范围内完成所传入操作的受众进行再营销。|
###|included_custom_actions|object[]|需包含的商品库受众的详细信息。<br>商品库受众基于用户与特定商品的互动，其效果通常优于自定义受众。|
####|code|string|用于筛选再营销受众的自定义操作。<br><br>枚举值：<ul><li>`VIEW_PRODUCT`：受众浏览了商品。</li><li>`ADD_TO_CART`：受众将商品加入了购物车。</li><li>`PURCHASE`：受众购买了商品。</li></ul>|
####|days|integer|用于筛选已完成所传入操作的受众的时间范围。|
###|excluded_custom_actions|object[]|需排除的商品库受众的详细信息。<br>通过排除用户已与之互动的商品来提升广告效果，确保用户只看到你的品牌的相关广告。|
####|code|string|用于排除受众的自定义操作。<br><br>枚举值：<ul><li>`VIEW_PRODUCT`：受众浏览了商品。</li><li>`ADD_TO_CART`：受众将商品加入了购物车。</li><li>`PURCHASE`：受众购买了商品。</li></ul>|
####|days|integer|用于排除已完成所传入操作的受众的时间范围。|
###|shopping_ads_retargeting_custom_audience_relation|string|通过 `shopping_ads_retargeting_type` 传入的再营销受众与通过 `audience_ids` 传入的自定义受众之间的逻辑关系。<br><br>枚举值：<ul><li>`OR`：基于再营销受众和自定义受众的并集创建目标受众。广告组将针对商品库受众或自定义受众中的任意用户定向投放。</li><li>`AND`：基于再营销受众和自定义受众的交集创建目标受众。广告组将针对既属于再营销受众又属于自定义受众的用户定向投放。</li></ul>|
###|included_pangle_audience_package_ids |string[]|你希望包含的 Pangle 受众 ID。 |
###|excluded_pangle_audience_package_ids |string[]|你希望排除的 Pangle 受众 ID。 |
###|interest_category_ids |string[]|你希望用来定向受众的大众兴趣关键词 ID。|
###|interest_keyword_ids |string[]|你希望用来定向受众的其他兴趣类别 ID。<br><br>若想搜索其他兴趣类别，需使用 [/targeting/search/](1796638342793218.html) 接口（推荐）或 [/tool/interest_keyword/recommend/](1763590884474882.html) 接口。|
###|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[]|在某个用户行为类型下，你希望定向的具体用户互动。<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)。|
###|smart_audience_enabled |boolean|是否启用智能受众。<br><br>支持的值：`true`、`false`。<br><br>如需详细了解智能受众以及如何启用智能受众，参见[智能定向](1783164662979586.html)。|
###|spending_power |string|你希望定向的消费能力。<br><br>枚举值：`ALL`、`HIGH`。<br><br>如果该值设置为 `HIGH`，你可以定向高消费用户，这些用户在 TikTok 广告引导下的购买支出通常高于平均水平。|
###|household_income |string[]|你希望定向的家庭收入。<br><br>枚举值：`TOP5`（邮政编码地区的前 5%）、`TOP10`（邮政编码地区的前 10%）、`TOP10_25`（邮政编码地区的前 10% - 25%）、`TOP25_50`（邮政编码地区的前 25% - 50%）。|
###|min_android_version |string|最低 Android 版本。<br><br>枚举值参见[枚举值 - 最低 Android 版本](https://business-api.tiktok.com/portal/docs?id=1737174886619138#item-link-Minimum%20Android%20Version)。|
###|min_ios_version |string|受众最低 iOS 版本。<br><br>枚举值参见[枚举值 - 最低 iOS 版本](https://business-api.tiktok.com/portal/docs?id=1737174886619138#item-link-Minimum%20iOS%20Version)。|
###|device_model_ids |string[]|设备型号 ID 列表。 |
###|network_types |string[]|你希望定向的网络类型。<br><br>枚举值参见[枚举值 - 网络类型](https://business-api.tiktok.com/portal/docs?id=1737174886619138#item-link-Connection%20Type)。|
###|carrier_ids |string[]|你希望定向的运营商。 |
###|isp_ids |string[]|定向的互联网服务提供商的 ID。|
###|device_price_ranges |number[]|定向设备价格范围。10,000 表示 1,000 以上。数字必须为 50 的倍数。<br><br><p><span style="color:darkred"><b>重要说明</b></span>：系统会在你设置的上限基础上再加 50，并将所得的新数值用作设备定向的实际上限。实际上限会在 TikTok 广告管理平台的广告组设置中显示。如果你设置的价格范围为 [0, 250]，系统实际上会按 [0, 300] 处理。</p>|
###|saved_audience_id |string|当创建广告组时，传入 `saved_audience_id` 后返回。<br><br>已保存受众 ID。|
###|blocked_pangle_app_ids |string[]|Pangle 应用屏蔽 ID 列表。|
###|brand_safety_type |string|Smart+ 推广系列的库存筛选层级。<br><br>枚举值：<ul><li>`EXPANDED_INVENTORY`：扩展库存。你的广告不会展示在明显不适当的内容前后，但可能会展示在成人主题内容前后。</li><li>`STANDARD_INVENTORY`：标准库存。你的广告将展示在适合大多数品牌的内容前后。</li><li>`LIMITED_INVENTORY`：有限库存。你的广告不会展示在包含成人主题的内容前后。</li><li>`NO_BRAND_SAFETY`：不使用任何品牌安全解决方案的全部库存，这意味着你的广告可能会展示在某些成人主题的内容前后。</li></ul><br><p><span style="color:darkred"><b>注意</b></span>：系统会根据你的[品牌安全中心](https://business-api.tiktok.com/portal/docs?id=1739381752981505#item-link-Brand%20Safety%20Hub)配置自动应用此设置。若想获取广告账号此类设置的详细信息，需使用 [/tiktok_inventory_filters/get/](1830112550443073.html) 接口。</p>|
###|category_exclusion_ids |string[]|内容排除类别 ID。|
##| 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`。|
##|placement_type |string[]|决定你的广告将在哪里展示的广告位策略。<br><br>枚举值： <ul><li>`PLACEMENT_TYPE_AUTOMATIC`：自动广告位。</li><li>`PLACEMENT_TYPE_NORMAL`：选择广告位。</li></ul>|
##|placements |string[]|你希望投放广告的应用。<br><br>枚举值： <ul><li>`PLACEMENT_TIKTOK`：TikTok。</li><li>`PLACEMENT_PANGLE`：Pangle。</li><li>`PLACEMENT_GLOBAL_APP_BUNDLE`：全球化应用组合。</li></ul>|
##|tiktok_subplacements|string[]|TikTok 子广告位，可供你选择广告的展示位置。<br><br>枚举值：<ul><li>`LEMON8`：Lemon8，一款生活方式内容社区应用，内容包含真实生活体验分享、小贴士、指南和商品测评。如果选择 Lemon8 作为子广告位，广告将展示在其推荐页信息流、搜索信息流和沉浸式视频信息流中。[详细了解 Lemon8 效果竞价广告](https://ads.tiktok.com/help/article/about-lemon8-in-tiktok-ads-manager)。</li><li>`PINE_DRAMA`：PineDrama，一款观看短剧的应用。广告将被投放在推荐页面、剧集信息流等位置。[详细了解 PineDrama 效果竞价广告](https://ads.tiktok.com/help/article/about-pinedrama-for-performance-auction-in-tiktok-ads-manager)。</li></ul>|
##|search_result_enabled |boolean|是否在“搜索广告”中包含你的广告，即当用户在 TikTok 上搜索你的业务相关信息时向其展示你的广告。<br><br>支持的值：`true`、`false`。|
##|comment_disabled |boolean|是否允许在 TikTok 上评论你的广告。<br><br>支持的值：`true`、`false`。|
##|share_disabled |boolean|是否禁止将推广系列分享到第三方平台。<br><br>支持的值：`true`、`false`。|
##|video_download_disabled |boolean|用户是否可以在 TikTok 上下载你的视频广告。<br><br>支持的值：`true`、`false`。|
##|skip_learning_phase |boolean|是否跳过学习阶段。<br><br>支持的值：`true`。|
##|create_time |string|创建广告组的时间，格式为 `YYYY-MM-DD HH:MM:SS` (UTC+0)。<br><br>示例：`2025-01-01 00:00:01`。|
##|modify_time |string|最后修改广告组的时间，格式为 `YYYY-MM-DD HH:MM:SS` (UTC+0)。<br><br>示例：`2025-01-01 00:00:01`。|
#|page_info |object|分页信息。|
##|page |number|当前页码。|
##|page_size |number|分页大小。|
##|total_number |number|结果总数。|
##|total_page |number|结果总页数。|
示例
(code Success-Response http)
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"list": [
{
"adgroup_id": "{{adgroup_id}}",
"adgroup_name": "{{adgroup_name}}",
"advertiser_id": "{{advertiser_id}}",
"bid_type": "BID_TYPE_NO_BID",
"billing_event": "CPC",
"budget": 0,
"budget_mode": "BUDGET_MODE_INFINITE",
"campaign_id": "{{campaign_id}}",
"campaign_name": "{{campaign_name}}",
"catalog_authorized_bc_id": "{{catalog_authorized_bc_id}}",
"catalog_id": "{{catalog_id}}",
"comment_disabled": false,
"conversion_bid_price": 0,
"create_time": "{{create_time}}",
"dayparting": "111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111",
"modify_time": "{{modify_time}}",
"operation_status": "ENABLE",
"optimization_goal": "CLICK",
"pacing": "PACING_MODE_SMOOTH",
"placement_type": "PLACEMENT_TYPE_AUTOMATIC",
"placements": [
"PLACEMENT_TIKTOK"
],
"product_source": "CATALOG",
"promotion_type": "WEBSITE",
"promotion_website_type": "UNSET",
"schedule_end_time": "{{schedule_end_time}}",
"schedule_start_time": "{{schedule_start_time}}",
"schedule_type": "SCHEDULE_START_END",
"search_result_enabled": true,
"secondary_status": "ADGROUP_STATUS_TIME_DONE",
"share_disabled": false,
"targeting_optimization_mode": "AUTOMATIC",
"targeting_spec": {
"age_groups": [
"AGE_18_24",
"AGE_25_34",
"AGE_35_44",
"AGE_45_54",
"AGE_55_100"
],
"brand_safety_type": "EXPANDED_INVENTORY",
"gender": "GENDER_UNLIMITED",
"location_ids": [
"3686110"
],
"spc_audience_age": "OVER_EIGHTEEN",
"spending_power": "ALL"
},
"video_download_disabled": false
},
{
"adgroup_id": "{{adgroup_id}}",
"adgroup_name": "{{adgroup_name}}",
"advertiser_id": "{{advertiser_id}}",
"attribution_event_count": "EVERY",
"bid_type": "BID_TYPE_NO_BID",
"billing_event": "OCPM",
"budget": 0,
"budget_mode": "BUDGET_MODE_INFINITE",
"campaign_id": "{{campaign_id}}",
"campaign_name": "{{campaign_name}}",
"catalog_authorized_bc_id": "{{catalog_authorized_bc_id}}",
"catalog_id": "{{catalog_id}}",
"click_attribution_window": "SEVEN_DAYS",
"comment_disabled": false,
"conversion_bid_price": 0,
"create_time": "{{create_time}}",
"dayparting": "111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111",
"modify_time": "{{modify_time}}",
"operation_status": "ENABLE",
"optimization_event": "ADD_BILLING",
"optimization_goal": "CONVERT",
"pacing": "PACING_MODE_SMOOTH",
"pixel_id": "{{pixel_id}}",
"placement_type": "PLACEMENT_TYPE_AUTOMATIC",
"placements": [
"PLACEMENT_TIKTOK"
],
"product_source": "CATALOG",
"promotion_type": "WEBSITE",
"promotion_website_type": "UNSET",
"schedule_end_time": "{{schedule_end_time}}",
"schedule_start_time": "{{schedule_start_time}}",
"schedule_type": "SCHEDULE_START_END",
"search_result_enabled": true,
"secondary_status": "ADGROUP_STATUS_TIME_DONE",
"share_disabled": false,
"skip_learning_phase": true,
"targeting_optimization_mode": "AUTOMATIC",
"targeting_spec": {
"age_groups": [
"AGE_18_24",
"AGE_25_34",
"AGE_35_44",
"AGE_45_54",
"AGE_55_100"
],
"brand_safety_type": "EXPANDED_INVENTORY",
"gender": "GENDER_UNLIMITED",
"location_ids": [
"6252001"
],
"spc_audience_age": "OVER_EIGHTEEN",
"spending_power": "ALL"
},
"video_download_disabled": false,
"view_attribution_window": "ONE_DAY"
},
{
"adgroup_id": "{{adgroup_id}}",
"adgroup_name": "{{adgroup_name}}",
"advertiser_id": "{{advertiser_id}}",
"app_id": "{{app_id}}",
"attribution_event_count": "EVERY",
"bid_type": "BID_TYPE_NO_BID",
"billing_event": "OCPM",
"budget": 0,
"budget_mode": "BUDGET_MODE_INFINITE",
"campaign_id": "{{campaign_id}}",
"campaign_name": "{{campaign_name}}",
"click_attribution_window": "SEVEN_DAYS",
"comment_disabled": false,
"conversion_bid_price": 0,
"create_time": "{{create_time}}",
"dayparting": "111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111",
"deep_bid_type": "AEO",
"engaged_view_attribution_window": "SEVEN_DAYS",
"modify_time": "{{modify_time}}",
"operation_status": "ENABLE",
"optimization_event": "ACTIVE_PAY",
"optimization_goal": "IN_APP_EVENT",
"pacing": "PACING_MODE_SMOOTH",
"placement_type": "PLACEMENT_TYPE_AUTOMATIC",
"placements": [
"PLACEMENT_TIKTOK",
"PLACEMENT_GLOBAL_APP_BUNDLE",
"PLACEMENT_PANGLE"
],
"promotion_type": "APP_ANDROID",
"schedule_end_time": "{{schedule_end_time}}",
"schedule_start_time": "{{schedule_start_time}}",
"schedule_type": "SCHEDULE_START_END",
"search_result_enabled": true,
"secondary_status": "ADGROUP_STATUS_TIME_DONE",
"share_disabled": false,
"skip_learning_phase": true,
"targeting_optimization_mode": "AUTOMATIC",
"targeting_spec": {
"age_groups": [
"AGE_18_24",
"AGE_25_34",
"AGE_35_44",
"AGE_45_54",
"AGE_55_100"
],
"brand_safety_type": "EXPANDED_INVENTORY",
"gender": "GENDER_UNLIMITED",
"location_ids": [
"1562822"
],
"operating_systems": [
"ANDROID"
],
"spc_audience_age": "OVER_EIGHTEEN",
"spending_power": "ALL"
},
"video_download_disabled": false,
"view_attribution_window": "ONE_DAY"
}
],
"page_info": {
"page": 1,
"page_size": 1000,
"total_number": 3,
"total_page": 1
}
}
}
(/code)