生成升级版 Smart+ 素材细分报表

此接口可用于获取升级版 Smart+ 素材细分报表，即升级版 Smart+ 广告中各创意素材的报表细分数据。

升级版 Smart+ 素材细分报表支持按时间范围（小时、天、周或月）分项展示。

请求

地址 https://business-api.tiktok.com/open_api/v1.3/smart_plus/material_report/breakdown/

方法 GET

Header

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

参数

|字段{30%}|类型{15%}|描述{55%}|
|--- |--- |--- |
| advertiser_id {必填} | string | 广告主 ID。 |
| dimensions {必填} | string[] | 维度分组条件。<br><br>例如，`&#91;"main_material_id","stat_time_day"&#93;` 表示 `main_material_id` 和 `stat_time_day` 都已分组。<br><br>要了解可用的维度和支持的维度分组，参见[支持的维度](1843337879988226.html)。 |
| metrics | string[] | 要查询的指标。<br><br>默认值：`&#91;"spend", "impressions"&#93;`。<br><br>注意，币种指标的金额以广告账号 (`advertiser_id`) 的币种为准。<br><br>要了解广告层级支持的指标，参见[升级版 Smart+ 素材报表支持的广告层级指标](1843337909199938.html)。 |
| filtering | object | 筛选条件。 |
#| campaign_ids | string[] | 推广系列 ID 列表。<br><br>最大数量：200。<br><br>若想获取推广系列 ID，需使用 [/smart_plus/campaign/get/](1843312818332930.html) 接口。<br><br><ul><li>筛选条件组合规则：筛选条件 `campaign_ids` 不能与筛选条件 `adgroup_ids` 或 `smart_plus_ad_ids` 组合使用。</li><li>筛选条件和维度组合规则：筛选条件可以与以下任何维度组合使用：<ul><li>`advertiser_id`</li><li>`campaign_id`</li><li>`adgroup_id`</li><li>`smart_plus_ad_id`</li></ul></li></ul>  |
#| adgroup_ids | string[] | 推广系列 ID 列表。<br><br>最大数量：200。<br><br>若想获取广告组 ID，需使用 [/smart_plus/adgroup/get/](1843314879617026.html) 接口。<br><br><ul><li> 筛选条件组合规则：筛选条件 `campaign_ids` 不能与筛选条件 `adgroup_ids` 或 `smart_plus_ad_ids` 组合使用。</li><li>筛选条件和维度组合规则：筛选条件可以与以下任何维度组合使用：<ul><li>`advertiser_id`</li><li>`campaign_id`</li><li>`adgroup_id`</li><li>`smart_plus_ad_id`</li></ul></li></ul>|
#| smart_plus_ad_ids | string[] | 广告 ID 列表。<br><br>最大数量：200。<br><br>若想获取广告 ID，需使用 [/smart_plus/ad/get/](1843317378982914.html) 接口。<br><br><ul><li>筛选条件组合规则：筛选条件 `smart_plus_ad_ids` 不能与筛选条件 `campaign_ids` 或 `adgroup_ids` 组合使用。</li><li> 筛选条件和维度组合规则：筛选条件可以与以下任何维度组合使用：<ul><li>`advertiser_id`</li><li>`smart_plus_ad_id`</li></ul></li></ul> |
#| main_material_types | string[] | 主要创意素材类型列表。<br><br>枚举值：<ul><li>`VIDEO_NON_SPARK_ADS`：视频（非 Spark Ads）。</li><li>`VIDEO_SPARK_ADS`：视频 (Spark Ads)。</li><li>`CAROUSEL_NON_SPARK_ADS`：轮播（非 Spark Ads）。</li><li>`CAROUSEL_SPARK_ADS`：轮播 (Spark Ads)。</li><li>`SINGLE_IMAGE_NON_SPARK_ADS`：单图广告（非 Spark Ads）。</li><li>`CATALOG_VIDEO`：商品库视频。</li><li>`CATALOG_VIDEO_TEMPLATE`：商品库视频模板。</li><li>`CATALOG_CAROUSEL`：商品库轮播。</li><li>`CATALOG_MULTI_SHOW`：商品库多影片。</li></ul><br><ul><li>筛选条件组合规则：可单独使用筛选条件 `main_material_types`。</li><li>筛选条件和维度组合规则：筛选条件可以与以下任何维度组合使用：<ul><li>`advertiser_id`</li><li>`campaign_id`</li><li>`adgroup_id`</li><li>`smart_plus_ad_id`</li></ul></li></ul> |
#| main_material_ids | string[] | 主要创意素材 ID 列表。<br><br><ul><li>筛选条件组合规则：使用此筛选条件时，总共可以为筛选条件 `main_material_ids`、`ad_text_entity_ids`、`call_to_action_entity_ids` 和 `interactive_add_on_entity_ids` 指定最多 400 个 ID。</li><li>筛选条件和维度组合规则：筛选条件可以与以下任何维度组合使用：<ul><li>`advertiser_id`</li><li>`campaign_id`</li><li>`adgroup_id`</li><li>`smart_plus_ad_id`</li></ul> </li></ul> |
#| ad_text_entity_ids | string[] | 广告文案主体 ID 列表。<br><br>此 ID 是系统为广告文案生成的唯一标识。<br><br><ul><li>筛选条件组合规则：使用此筛选条件时，总共可以为筛选条件 `main_material_ids`、`ad_text_entity_ids`、`call_to_action_entity_ids` 和 `interactive_add_on_entity_ids` 指定最多 400 个 ID。</li><li>筛选条件和维度组合规则：筛选条件可以与以下任何维度组合使用：<ul><li>`advertiser_id`</li><li>`campaign_id`</li><li>`adgroup_id`</li><li>`smart_plus_ad_id`</li></ul></li></ul> |
#| call_to_action_entity_ids | string[] | 行动引导文案主体 ID 列表。<br><br>此 ID 是系统为行动引导文案生成的唯一标识。<br><br><ul><li>筛选条件组合规则：使用此筛选条件时，总共可以为筛选条件 `main_material_ids`、`ad_text_entity_ids`、`call_to_action_entity_ids` 和 `interactive_add_on_entity_ids` 指定最多 400 个 ID。</li><li> 筛选条件和维度组合规则：筛选条件可以与以下任何维度组合使用：<ul><li>`advertiser_id`</li><li>`campaign_id`</li><li>`adgroup_id`</li><li>`smart_plus_ad_id`</li></ul></li></ul>  |
#| interactive_add_on_entity_ids | string[] | 创新互动样式主体 ID 列表。<br><br>此 ID 是系统为创新互动样式生成的唯一标识。<br><br><ul><li>筛选条件组合规则：使用此筛选条件时，总共可以为筛选条件 `main_material_ids`、`ad_text_entity_ids`、`call_to_action_entity_ids` 和 `interactive_add_on_entity_ids` 指定最多 400 个 ID。</li><li>筛选条件和维度组合规则：筛选条件可以与以下任何维度组合使用：<ul><li>`advertiser_id`</li><li>`campaign_id`</li><li>`adgroup_id`</li><li>`smart_plus_ad_id`</li></ul> </li></ul> |
| start_date {必填} | string | 查询开始日期（闭区间），格式为 `YYYY-MM-DD`。<br><br>日期以广告账号的时区为准。 |
| end_date {必填} | string | 查询结束日期（闭区间），格式为 `YYYY-MM-DD`。<br><br>日期以广告账号的时区为准。<br><br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>`start_date` 和 `end_date` 之间的时间间隔不得超过 365 天。</li><li>如果 `dimensions` 包含 `stat_time_hour`，那么 `start_date` 和 `end_date` 之间的时间间隔不得超过 7 天</li></ul></p> |
| sort_field | string | 排序字段。<br><br>默认排序字段：`spend`。<br><br>所有支持的指标（不包括属性指标）都支持排序。 |
| sort_type | string | 排序的顺序。<br><br>枚举值：`ASC`（升序）、`DESC`（降序）。<br>默认值：`DESC`。 |
| page | number | 当前页码。<br><br>值范围：≥1。<br>默认值：1。 |
| page_size | number | 页面大小。<br><br>值范围：1-100。<br>默认值：10。 |

示例

(code curl http)
curl --location--request GET 'https://business-api.tiktok.com/open_api/v1.3/smart_plus/material_report/breakdown/?advertiser_id={{advertiser_id}}&dimensions=["main_material_id","ad_text_entity_id"]&metrics=["spend","clicks"]&filtering={"adgroup_ids": ["{{adgroup_id}}"]}&&start_date={{start_date}}&end_date={{end_date}}&page=1&page_size=100' \
--header 'Access-Token: {{Access-Token}}'
(/code)

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|code |number|返回码。完整返回码列表及描述参见[附录 - 返回码](1737172488964097.html)。|
|message|string|返回信息。更多信息参见[附录 - 返回码](1737172488964097.html)。|
|request_id|string|请求的日志 ID，用于唯一标识该请求。|
|data|object|返回的数据。|
#| list|object[]|数据列表。|
##| dimensions|object|维度数据。|
###| main_material_id|string|请求中的参数 `dimensions` 包含 `main_material_id` 时返回。<br><br>素材 ID。<br><br><ul><li>当 `main_material_type` 为 `VIDEO_NON_SPARK_ADS`、`CATALOG_VIDEO` 或 `SINGLE_IMAGE_NON_SPARK_ADS`，此字段表示主要创意素材的 ID。</li><li>当 `main_material_type` 为 `VIDEO_SPARK_ADS` 或 `CAROUSEL_SPARK_ADS`，此字段表示 TikTok 帖子的 ID。</li><li>当 `main_material_type` 为 `CATALOG_VIDEO_TEMPLATE`、`CATALOG_CAROUSEL` 或 `CATALOG_MULTI_SHOW`，此字段表示商品库的 ID。</li><li>当 `main_material_type` 为 `CAROUSEL_NON_SPARK_ADS`，此字段表示轮播的 ID。</li></ul>|
###| main_material_type|string|主要创意素材类型。<br><br>枚举值：<ul><li>`VIDEO_NON_SPARK_ADS`：视频（非 Spark Ads）。</li><li>`VIDEO_SPARK_ADS`：视频 (Spark Ads)。</li><li>`CAROUSEL_NON_SPARK_ADS`：轮播（非 Spark Ads）。</li><li>`CAROUSEL_SPARK_ADS`：轮播 (Spark Ads)。</li><li>`SINGLE_IMAGE_NON_SPARK_ADS`：单图广告（非 Spark Ads）。</li><li>`CATALOG_VIDEO`：商品库视频。</li><li>`CATALOG_VIDEO_TEMPLATE`：商品库视频模板。</li><li>`CATALOG_CAROUSEL`：商品库轮播。</li><li>`CATALOG_MULTI_SHOW`：商品库多影片。</li></ul>|
###| ad_text_entity_id|string|广告文案主体 ID。<br><br>此 ID 是系统为广告文案生成的唯一标识。|
###| ad_text_entity_type|string|广告文案主体类型。<br><br>枚举值：<ul><li>`text`：广告文案。</li></ul>|
###| call_to_action_entity_id|string|行动引导文案主体 ID。<br><br>此 ID 是系统为行动引导文案生成的唯一标识。|
###| call_to_action_entity_type|string|行动引导文案主体类型。<br><br>枚举值：<ul><li>`manual_call_to_action`：标准行动引导文案。</li><li>`dynamic_call_to_action`：动态行动引导文案。</li></ul>|
###| interactive_add_on_entity_id|string|创新互动样式主体 ID。<br><br>此 ID 是系统为创新互动样式生成的唯一标识。|
###| interactive_add_on_entity_type|string|创新互动样式主体类型。<br><br>枚举值：<ul><li>`add_on`：创新互动样式。</li></ul>|
##| metrics|object|指标数据。|
###| {metric_name}|string|返回的指标，由请求中指定的 `metrics` 字段决定。|
###| multi_name|string|根据请求中指定的设置维度（`ad_text_entity_ids`、`call_to_action_entity_ids` 和 `interactive_add_on_entity_ids`）生成的设置名称组合。<br><br>例如，如果你在请求中指定维度 `ad_text_entity_ids` 和 `call_to_action_entity_ids`，那么 `multi_name` 将为 `&#123;ad_text_name&#125;_&#123;call_to_action_name&#125;`。<br><br>示例：`Video1_Adtext1_CTA1`。|
###| main_material_name|string|主要创意素材名称。|
###| ad_text|string|广告文案。|
###| call_to_action|string|行动引导文案。|
###| interactive_add_on_name|string|创新互动样式名称。|
###| interactive_add_on_id|string|创新互动样式 ID。<br><br>在创意素材库中创建创新互动样式时，会生成此 ID，并且此 ID 与 `interactive_add_on_entity_id` 不同。|
#| 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": [
            {
                "dimensions": {
                    "ad_text_entity_id": "{{ad_text_entity_id}}",
                    "ad_text_entity_type": "text",
                    "main_material_id": "{{main_material_id}}",
                    "main_material_type": "CAROUSEL_SPARK_ADS"
                },
                "metrics": {
                    "ad_text": "{{ad_text}}",
                    "clicks": "{{clicks}}",
                    "main_material_name": "{{main_material_name}}",
                    "multi_name": "{{multi_name}}",
                    "spend": "{{spend}}"
                }
            }
        ],
        "page_info": {
            "page": 1,
            "page_size": 100,
            "total_number": 1,
            "total_page": 1
        }
    }
}
(/code)