← 返回目录
📁 API Reference › Creative Reports

创意基础报表

请求创意基础报表

您可以使用本接口请求创意基础报表。

注意
创意基础报表包含了未删除和已删除的创意素材的数据。

使用前需知

您需先使用/ad/create/，/ad/aco/create/或/campaign/spc/create/创建广告或推广系列，确保创意层级产生了消耗数据。若您未创建任何广告或推广系列，或您的广告或推广系列未产生消耗，则可能返回空结果。

v1.2与v1.3版本对比

以下表格概括了 v1.2与v1.3接口的变化。 ``xtable |变化内容{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| |接口路径| /v1.2/creative/reports/get/|/v1.3/creative/report/get/| |请求参数名称|order_field<br>order_type|sort_field<br>sort_type| |请求参数类型|advertiser_id: number <br>ad_id: number[] <br>adgroup_id: number[] <br>campaign_id: number[]<br>country_code: list|advertiser_id: string <br>ad_id: string[] <br>adgroup_id: string[] <br>campaign_id: string[]<br>country_code: string[]| |废弃请求参数|/|image_mode| |返回参数名称|ad_number|num_ads| |返回参数类型|country_code: list[string]<br>placement: list[string]|country_code: string[]<br>placement: string[]| |返回参数名称和类型|related_ads: number[] <br>related_adgroups: number[]|related_ad_ids: string[] <br>related_adgroup_ids: string[]| |废弃返回参数|/|ad_cost_top5<br>ad_cost_top5_total<br>adgroup_cost_top5<br>adgroup_cost_top5_total`|


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

**方法** GET

**Header**

```xtable
|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
|Content-Type {必填}|string|请求信息类型。<br>允许格式：`application/json`。|

参数

|字段|类型|描述|
|---|---|---|
| advertiser_id{必填} |  string| 广告主 ID。 |
| material_type{必填} | string | 素材类型。 枚举值：`VIDEO`、 `IMAGE`, `INSTANT_PAGE`。 |
| lifetime | boolean | 是否查询全部的数据。<br><br>如果本字段设置为`true`，则不需要指定 `start_date` 和 `end_date`。<br><br>支持的值：`true`, `false`。<br><br>默认值：`false`。 |
| start_date{+ 条件必填} | string | 当`lifetime`为`false`时必填。<br><br>起始时间，闭区间。格式如：2020-01-01（广告主时区）。 |
| end_date{+ 条件必填} | string | 当`lifetime`为`false`时必填。<br><br>结束时间，闭区间。格式如：2020-01-01（广告主时区）。|
|info_fields|string[]|您需要的有关创意素材的信息。默认值： [`material_id`, `video_id`, `image_id`, `page_id`]。可选范围：返回值中`info`下的所有字段。|
| metrics_fields | string[] | 您需要的指标或者维度数据。默认值：[`impressions` , `spend`]。可选范围：返回值中`metrics`下的所有字段。 |
| filtering | object | 筛选条件。 |
#| material_id | string[] | 素材ID。最多可传入10个ID。 |
#| material_name | string | 素材名称。支持模糊搜索。 |
#|ad_name| string| 广告名称。支持模糊搜索。|
#|ad_id| string[] |您希望用作筛选条件的广告ID列表。支持批量请求。|
#|adgroup_name| string |您希望用作筛选条件的广告组名称。支持模糊搜索。 |
#|adgroup_id| string[] |您希望用作筛选条件的广告组ID。支持批量请求。|
#|campaign_name| string | 您希望用作筛选条件的推广系列名称。支持模糊搜索。|
#|campaign_id|string[]| 您希望用作筛选条件的推广系列ID。支持批量请求。|
#| country_code | string[]| 国家或地区代码。枚举值见：[附录-地区代码](https://ads.tiktok.com/marketing_api/docs?id=1737585867307010)。|
#| placement | string[]| 投放版位。枚举值见：[枚举值-版位](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
#|page_id|string[]|落地页ID列表。|
#|page_status|string[]|落地页状态。枚举: `DRAFT`（草稿）, `READY`（可用）。|
#|page_biz_type|string[]|落地页业务类型。枚举: `CUSTOM`（定制）, `APP_PROFILE`（应用信息）, `INSTANT_FORM`（即时表单）。|
#|page_template_type|string[]|落地页模板类型列表。在`page_biz_type` 中包含 `CUSTOM`时，枚举值为：<ul><li>`CUSTOMIZED`（定制）</li><li>`INTRODUCTION`（介绍）</li><li>`BRAND_STORY`（品牌故事）</li><li>`SALES_PRODUCT`（产品销售）</li><li>`MOVIE_TRAILER`（电影预告）</li></ul>在`page_biz_type` 包含 `INSTANT_FORM`时，枚举值为`NORMAL_FORM`（常规表单），`ADVANCED_FORM`（复杂表单）。|
#|app_profile_country|string[]|落地页配置的国家或地区代码列表。只在`instant_page_biz_type`包含 `APP_PROFILE`时有效。|
#|app_profile_external_app_id|string[]|落地页导向的应用的ID。只在`instant_page_biz_type`包含 `APP_PROFILE`时有效。|
#|customized_page_external_action|string[]|定制落地页特有的转化事件。|
#| spend | object | 消耗范围。 |
##| min | float | 最小值，开区间。不填表示不限制最小值。 |
##| max | float | 最大值，开区间。不填表示不限制最大值。 |
#| conversion | object | 转化值。 |
##| min | float | 最小值，开区间。不填表示不限制最小值。 |
##| max | float | 最大值，开区间。不填表示不限制最大值。 |
| sort_field | string | 排序字段。支持按照素材创建时间以及所有的指标数据进行排序。默认不排序。 |
| sort_type | string | 排序方式。枚举值：`ASC`, `DESC`。 默认值：`DESC`。 |
| page | number | 当前页数。默认值：1，取值范围：≥ 1 |
| page_size | number | 分页大小。默认值：10，取值范围：1-1000 |

示例

(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/creative/report/get/?advertiser_id={{advertiser_id}}&material_type=VIDEO&lifetime=false&start_date=2023-01-01&end_date=2023-08-01&info_fields=["material_id", "video_id", "image_id","page_id"]&metrics_fields=["spend","impressions","clicks"]&page=1&page_size=10' \
--header 'Access-Token: {{Access-Token}}'
(/code)

返回

|字段|类型|描述|
|---|---|---|
|code |number|返回码，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string|返回信息，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|data |object|返回数据。  |
#|list |object[]| 报表信息。|
##| info | object | 素材信息。 |
###| material_id | string | 素材 ID。 |
###| video_id | string | 视频 ID。|
###| image_id | string | 图片 ID。 |
###| source | string | 素材来源。枚举值见：[枚举值 - 素材来源](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
###| country_code | string[] | 国家编码。枚举值见：[附录-地区代码](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138) 。|
###| placement |  string[] | 投放版位。枚举值见：[枚举值 - 版位](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138) 。|
###| num_ads | number | 绑定的广告数量。 |
###| total_active_days | number | 累计活跃天数。若`spend` > 0，则当日计入活跃天。此字段仅支持`VIDEO`类型素材。<br><br><p><span style="color:darkred"><b>注意</b>：</span></p><ul><li>仅当请求中`lifetime`为 `false` 时支持本字段。</li><li>请求中 `lifetime` 设置为 `true` 时，本字段值将为 0。</li></ul>|
###| related_ad_ids | string[]| 关联的广告。此字段仅支持`VIDEO`类型素材。 |
###| adgroup_number  | number | 关联的广告组数量。此字段仅支持`VIDEO`类型素材。 |
###| related_adgroup_ids |string[] | 关联的广告组。此字段仅支持`VIDEO`类型素材。 |
###|page_id|string[]|落地页ID列表。|
###|page_status|string[]|落地页状态。枚举值: `DRAFT`（草稿）, `READY`（可用）|
###|page_biz_type|string[]|落地页业务类型。枚举值: `CUSTOM`（定制）, `APP_PROFILE`（应用信息）, `INSTANT_FORM`（即时表单）|
###|page_template_type|string[]|落地页模板类型列表。在`page_biz_type` 中包含 `CUSTOM`时，枚举值为：<ul><li>`CUSTOMIZED`（定制）</li><li>`INTRODUCTION`（介绍）</li><li>`BRAND_STORY`（品牌故事）</li><li>`SALES_PRODUCT`（产品销售）</li><li>`MOVIE_TRAILER`（电影预告）</li></ul>在`page_biz`type` 包含 `INSTANT_FORM`时，枚举值为`NORMAL_FORM`（常规表单）和`ADVANCED_FORM`（复杂表单）|
###|page_thumbnail|string|页面缩略图链接|
###|app_profile_country|string[]|落地页配置的国家代码列表。只在`instant_page_biz_type`包含 `APP_PROFILE`时有效|
###|app_profile_external_app_id|string[]|落地页导向的应用的ID。只在`instant_page_biz_type`包含 `APP_PROFILE`时有效|
###|app_profile_icon|string|应用图标|
###|customized_page_external_action|string[]|定制落地页特有的转化事件|
##| metrics | object | 指标。具体指标详情请参考[指标表](https://ads.tiktok.com/marketing_api/docs?id=1861363088053250)。 |
#|page_info |object|分页信息|
##|page |number|当前页数|
##|page_size |number|分页大小|
##|total_number |number|总数|
##|total_page |number|总页数|
|request_id |string|请求的日志id，唯一标识一个请求  |

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "list": [
            {
                "metrics": {
                    "clicks": "0",
                    "impressions": "0",
                    "spend": "0"
                },
                "info": {
                    "page_id": null,
                    "image_id": null,
                    "video_id": "{{video_id}}",
                    "material_id": "{{material_id}}"
                }
            },
            {
                "metrics": {
                    "clicks": "17",
                    "impressions": "30",
                    "spend": "0"
                },
                "info": {
                    "page_id": null,
                    "image_id": null,
                    "video_id": "{{video_id}}",
                    "material_id": "{{material_id}}"
                }
            },
            {
                "metrics": {
                    "clicks": "0",
                    "impressions": "0",
                    "spend": "0"
                },
                "info": {
                    "page_id": null,
                    "image_id": null,
                    "video_id": "{{video_id}}",
                    "material_id": "{{material_id}}"
                }
            },
            {
                "metrics": {
                    "spend": "0",
                    "clicks": "0",
                    "impressions": "0"
                },
                "info": {
                    "page_id": null,
                    "image_id": null,
                    "video_id": "{{video_id}}",
                    "material_id": "{{material_id}}"
                }
            },
            {
                "metrics": {
                    "spend": "0",
                    "clicks": "3",
                    "impressions": "3"
                },
                "info": {
                    "page_id": null,
                    "image_id": null,
                    "video_id": "{{video_id}}",
                    "material_id": "{{material_id}}"
                }
            },
            {
                "metrics": {
                    "clicks": "0",
                    "impressions": "0",
                    "spend": "0"
                },
                "info": {
                    "page_id": null,
                    "image_id": null,
                    "video_id": "{{video_id}}",
                    "material_id": "{{material_id}}"
                }
            },
            {
                "metrics": {
                    "clicks": "0",
                    "impressions": "0",
                    "spend": "0"
                },
                "info": {
                    "page_id": null,
                    "image_id": null,
                    "video_id": "{{video_id}}",
                    "material_id": "{{material_id}}"
                }
            },
            {
                "metrics": {
                    "clicks": "0",
                    "impressions": "0",
                    "spend": "0"
                },
                "info": {
                    "page_id": null,
                    "image_id": null,
                    "video_id": "{{video_id}}",
                    "material_id": "{{material_id}}"
                }
            },
            {
                "metrics": {
                    "impressions": "11",
                    "spend": "0",
                    "clicks": "1"
                },
                "info": {
                    "page_id": null,
                    "image_id": null,
                    "video_id": "{{video_id}}",
                    "material_id": "{{material_id}}"
                }
            },
            {
                "metrics": {
                    "spend": "0",
                    "clicks": "0",
                    "impressions": "0"
                },
                "info": {
                    "page_id": null,
                    "image_id": null,
                    "video_id": "{{video_id}}",
                    "material_id": "{{material_id}}"
                }
            }
        ],
        "page_info": {
            "total_number": 560,
            "total_page": 56,
            "page_size": 10,
            "page": 1
        }
    }
}
(/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 每日平台更新简报 →