← 返回目录
📁 API Reference › Reporting

请求同步报表

您可以使用本接口创建同步报表任务。

本接口目前最多能返回 20,000 条广告的报表数据。若您的广告数目超过 20,000 条，请使用campaign_ids/adgroup_ids/ad_ids作为筛选条件，分批获取全部广告的报表数据。若您使用campaign_ids/adgroup_ids/ad_ids作为筛选条件，单次最多传入 100 个 ID。

  • 欲了解请求同步报表的步骤，请查看生成同步报表。
  • 欲了解不同报表类型支持的维度、指标以及使用案例，请查看报表类型。
  • 欲了解广告服务类型、报表类型和报表数据层级之间的关系，请查看概览-数据层级。
  • 欲了解报表相关问题的问答，请查看常见问题。

重要提示
若想检索 GMV Max 推广系列的报表数据，需使用/gmv_max/report/get/为商品 GMV Max 推广系列或直播 GMV Max 推广系列生成 GMV Max 推广系列报表。

注意
若您将同步报表的数据与从 TikTok 广告管理平台下载的报表对比，您会发现数据不一致，因为TikTok广告管理平台下载的报表数据对应异步报表的数据，而非同步报表的数据。TikTok广告管理平台的下载报表与API中的异步报表均不进行20,000条数据截断。

v1.2与v1.3版本对比

以下表格概括了 v1.2与v1.3接口的变化。 ``xtable |变化内容{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| | 接口路径 | /v1.2/reports/integrated/get/ | /v1.3/report/integrated/get/ | |请求参数类型|advertiser_id: number |advertiser_id: string | | 请求参数名称|filters|filtering| | 废弃请求参数 | / |lifetime（由新请求参数query_lifetime替代） | | 新增请求参数| /|query_lifetime<br>bc_id<br> enable_total_metrics<br>advertiser_ids| |返回参数类型 |advertiser_id: number<br>campaign_id: number <br>adgroup_id: number<br>ad_id: number |advertiser_id: string<br>campaign_id: string <br>adgroup_id: string<br>ad_id: string | |新增返回参数| / |X-Tt-Ads-Throttle: string<br>contextual_tag`: string | |维度| / | 了解不同类型报表类型支持的维度的变动，请参考报表类型下的相应文章。 |指标| / | 了解不同类型报表类型支持的指标的变动，请参考报表类型下的相应文章。


# 请求

**地址**  <https://business-api.tiktok.com/open_api/v1.3/report/integrated/get/>

**方法** GET

**Header**

```xtable
|字段{25%}|类型{15%}|描述{60%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌，可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。  |

参数

|字段{25%}|类型{15%}|描述{60%}|
|---|---|---|
|advertiser_id {+条件必填}|string| 您需传入 `advertiser_id`，`advertiser_ids`和 `bc_id` 其中之一。<ul><li>若 `report_type` 设置为 `BASIC`  或 `AUDIENCE` ，需传入 `advertiser_id` 或`advertiser_ids`其中一个。若同时传入`advertiser_id` 和`advertiser_ids`，`advertiser_id`会被忽略。</li><li>若 `report_type` 设置为 `PLAYABLE_MATERIAL`，`CATALOG` 或 `TT_SHOP`， 需传入 `advertiser_id`。</li><li>若 `report_type` 设置为 `BC`，需传入 `bc_id` 。</li></ul><br>广告主 ID。|
|advertiser_ids {+条件必填}|string[]| 当`report_type`设置为 `BASIC`  或 `AUDIENCE` 时，需传入`advertiser_id`或`advertiser_ids`其中一个。如果您同时传入`advertiser_id`和`advertiser_ids`，`advertiser_id`会被忽略。<br>仅在`report_type`为`BASIC`或`AUDIENCE`时生效。<br><br>广告主ID列表。<br>最大数量：5。<br><br>当使用此字段时，请注意以下信息：<ul><li>当使用`advertiser_ids`时，将返回最多20,000个ID。ID的截取逻辑基于广告系列、广告组或广告的创建时间，按降序排列，但无法保证每个广告主都有均匀分布的ID数量。</li><li>当使用`advertiser_ids`时，返回的`metrics`数据将包括`currency`，`timezone`，和`advertiser_id`。</li><ul><li>不同的广告主可能有不同的时区。可以使用`multi_adv_report_in_utc_time`来决定将所有广告主返回的数据设为 UTC+0 时区，或设为各个广告主当地时区。 </li><li>不同的广告主可能有不同的货币，我们将在返回的`metrics`中为每个广告主返回对应的货币。这些指标数据没有小数点。例如，“100美元”的花费将显示为100，没有小数点符号，如“.000”。</li></ul><li>如果您想查看所有广告主ID的汇总指标，请在请求中开启`enable_total_metrics`字段。返回中的`total_metrics`将包括`currency`，`timezone`和 `advertiser_id`，值都为`-`。</li></ul><br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>若使用`advertiser_ids`，但`dimensions`字段中不包括任何ID维度，则返回的`metrics`中`currency`，`timezone`和 `advertiser_id`的值将返回`0`，<b>与成本相关的指标</b>（例如`spend`）的将返回`-`。</li><li>`advertiser_ids`中指定的广告主应属于同一个TikTok for Business用户。否则会出错。使用[/oauth2/advertiser/get/](1738455508553729.html)接口来获取同一个TikTok for Business用户的广告主ID列表。</li></ul>|
|bc_id {+条件必填}|string| 您需传入 `advertiser_id`/`advertiser_ids` 和 `bc_id` 其中之一。<ul><li>若 `report_type` 设置为 `BASIC`  或 `AUDIENCE` ，需传入 `advertiser_id`或`advertiser_ids` 。</li><li>若 `report_type` 设置为 `PLAYABLE_MATERIAL`，`CATALOG` 或 `TT_SHOP`， 需传入 `advertiser_id`。</li><li>若 `report_type` 设置为 `BC`，需传入 `bc_id` 。</li></ul><br>您有权访问的商务中心的 ID。<br><br>若想获取您有权访问的商务中心的 ID 列表，需使用[/bc/get/](1737115687501826.html)。 |
|service_type |string| `report_type` 设置为 `BC` 时不支持本字段。<br><br>广告服务类型。<br><br>枚举值：<ul><li>`AUCTION`：竞价广告，或竞价和合约广告。</li><li>`RESERVATION`（<span style="color:Red">已废弃</span>）：合约广告。 </li></ul><br>`report_type` 未设置为 `BC` 时的默认值: `AUCTION`。<br><br><p><span style="color:darkred"><b>注意</b></span>：若想拉取 TopView 广告的报表数据，可使用[基础报表](1738864915188737.html)或[受众分析报表](1738864928947201.html)，并在[筛选条件](1751443975608321.html) `buying_type` 中指定 `RESERVATION_TOP_VIEW` 。|
|report_type {必填}|string| 报表类型。<br><br>枚举值：<ul><li>`BASIC`：基础报表。</li><li>`AUDIENCE`：受众分析报表。</li><li>`PLAYABLE_MATERIAL` ：试玩素材报表。</li><li>`CATALOG`：DSA 报表。</li><li>`BC` ：商务中心报表。</li><li>`TT_SHOP`（<span style="color:Red">即将废弃</span>）：最大成交额广告报表。</li></ul><br><ul><li>当 `service_type` 为 `AUCTION`时，支持`BASIC`，`AUDIENCE`，`PLAYABLE_MATERIAL`，`CATALOG`和 `TT_SHOP` 报表。</li><li>当 `report_type` 为 `BC` 时，无需传入 `service_type`。</li></ul><br><p><span style="color:darkred"><b>重要提示</b></span>： 最大成交额广告报表（即`report_type` 为 `TT_SHOP` 时）仅提供有限数据，且将在下个 API 版本废弃。为确保流畅的集成体验，需使用[/gmv_max/report/get/](https://business-api.tiktok.com/portal/docs/run-a-gmv-max-campaign-report/v1.3)为商品 GMV Max 推广系列或直播 GMV Max 推广系列生成 GMV Max 推广系列报表。 |
|data_level {+条件必填} |string| `report_type` 设置为 `BC` 时不支持本字段。<br>当`report_type`为 `BASIC`、`AUDIENCE` 或 `CATALOG` 时必填。<br><br>您想要查询的报表数据层级。<br><br>枚举值：<ul><li>`AUCTION_AD`：竞价广告或竞价和合约广告，广告层级。 </li><li>`AUCTION_ADGROUP`：竞价广告或竞价和合约广告，广告组层级。</li><li>`AUCTION_CAMPAIGN`：竞价广告或竞价和合约广告，推广系列层级。</li><li>`AUCTION_ADVERTISER`：竞价广告或竞价和合约广告，广告主层级。</li><li>`RESERVATION_AD`（<span style="color:Red">已废弃</span>）：合约广告，广告层级。</li><li>`RESERVATION_ADGROUP`（<span style="color:Red">已废弃</span>）：合约广告，广告组层级。 </li><li>`RESERVATION_CAMPAIGN`（<span style="color:Red">已废弃</span>）：合约广告，推广系列层级。</li><li>`RESERVATION_ADVERTISER`（<span style="color:Red">已废弃</span>）：合约广告，广告主层级。</li></ul><br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>若您将本字段设置为`AUCTION_ADVERTISER`，则会同时返回广告主账号下的所有竞价广告和合约广告数据。</li><li>当`report_type`为`BASIC`，`AUDIENCE`或`CATALOG`时：<ul><li>若本字段设置为 `AUCTION_CAMPAIGN`，会返回非删除状态的竞价推广系列下所有广告的数据，因为默认应用了`campaign_status`为`STATUS_NOT_DELETE`的筛选条件。</li><li>若本字段设置为`AUCTION_ADGROUP`，会返回非删除状态的竞价广告组下所有广告的数据，因为默认应用了`adgroup_status`为`STATUS_NOT_DELETE`的筛选条件。</li><li>若本字段设置为 `AUCTION_AD`，会返回所有竞价推广系列下非删除状态的广告的数据，因为默认应用了`ad_status`为`STATUS_NOT_DELETE`的筛选条件。</li><li>若您想获取所有竞价推广系列下所有广告的数据，需将筛选条件 `ad_status`设置为`STATUS_ALL` （`filtering=[&#123;"field_name":"ad_status","filter_type":"IN","filter_value":"[\"STATUS_ALL\"]"&#125;]` ）。</li></ul></li><li>当 `report_type` 为 `TT_SHOP` 时，仅支持将本字段设置为 `AUCTION_ADVERTISER` 或 `AUCTION_CAMPAIGN`。</li></ul>|
|dimensions {必填}|string[]| 维度组合。示例：`&#91;"campaign_id", "stat_time_day"&#93;` 表示组合`campaign_id`和`stat_time_day`维度。 <br><br>不同报表类型支持的维度不同。<ul><li> 查看[基础报表](1751443956638721.html)中支持的维度。</li><li>查看[受众分析报表](1751454103714818.html)中支持的维度。</li><li>查看[试玩素材报表](1751617879104514.html)中支持的维度。</li><li>查看 [DSA 报表](1751617879104514.html)中支持的维度。</li><li>查看[商务中心报表](1775747465089026.html)中支持的维度。</li><li>查看[最大成交额广告报表](1803073629472770.html)中支持的维度。</li></ul><br><br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>若 `report_type` 未设置为`BC`：<ul><li>当`dimensions`包含 `stat_time_day` 时，查询时间范围不能超过 30 天，</li><li>当`dimensions`包含 `stat_time_hour` 时，查询时间范围不能超过 1 天。</li></ul> </li><li>若您查询的`dimensions`中不只包含 xx_id 且查询时间范围内没有广告报表，会返回空列表。</li></ul>|
|metrics |string[]|   要查询的指标。<br><br>不同报表类型支持的指标不同。欲了解不同类型报表类型支持的指标，请参考[报表类型](https://ads.tiktok.com/marketing_api/docs?id=1738864835805186)下的相应文章。<br><br><ul><li>若`report_type`设置为 `BASIC`，`AUDIENCE`，`PLAYABLE_MATERIAL` 或 `CATALOG`，默认值为`&#91;"spend", "impressions"&#93;`。</li><li>若`report_type`设置为`BC`，则默认值为通过`dimensions`指定的维度组合下支持的所有指标。</li><li> 若`report_type`设置为`TT_SHOP`，默认值为`&#91;"spend", "billed_cost"&#93;`。</li></ul> <br><p><span style="color:darkred"><b>注意</b></span>：与金额有关的货币数据指标会基于广告账户所设定的币种显示。|
| enable_total_metrics | boolean | 是否开启所请求指标的汇总数据。<br>当启用 `enable_total_metrics` 时，我们将在您查询不同页面时提供所有页面的汇总数据。在这种情况下，您只需在请求第一页数据时指定此字段。 <br>由于20,000 ID截断限制，启用 `enable_total_metrics` 时，我们将最多提供20,000个ID的汇总数据。 <br> <br><p><span style="color:darkred"><b>注意</b></span>: <ul><li>本字段仅支持竞价广告基础报表和最大成交额广告报表。</li><li>当在`dimensions`中只指定了一个 ID 维度和(或)`stat_time_day`参数时，本字段才生效。例如：`["campaign_id"]`, `["campaign_id", "stat_time_day"]`。 </li><li>不能在沙箱环境中使用本字段。</li></ul>|
|start_date {+条件必填} |string| 查询起始日期（闭区间），格式为`YYYY-MM-DD`。日期根据广告主时区设定。<br><br>若`query_lifetime` 未传入或设置为`false`，则本字段必填。<br><br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>若`report_type`未设置为`BC`且`dimensions`的值包含 `stat_time_day`，则允许通过`start_date` 和 `end_date` 指定的最长查询范围为 30 天。</li><li>若`report_type`未设置为`BC`且`dimensions`的值不包含 `stat_time_day`，则允许通过`start_date` 和 `end_date` 指定的最长查询范围为 365 天。</li><li>若`report_type`设置为`BC`，则允许通过`start_date` 和 `end_date` 指定的最长查询范围为 365 天。</li></ul> |
|end_date {+条件必填} |string|  查询结束日期（闭区间），格式为`YYYY-MM-DD`。日期根据广告主时区设定。<br><br>若`query_lifetime` 未传入或设置为`false`，则本字段必填。<br><br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>若`report_type`未设置为`BC`且`dimensions`的值包含 `stat_time_day`，则允许通过`start_date` 和 `end_date` 指定的最长查询范围为 30 天。</li><li>若`report_type`未设置为`BC`且`dimensions`的值不包含 `stat_time_day`，则允许通过`start_date` 和 `end_date` 指定的最长查询范围为 365 天。</li><li>若`report_type`设置为`BC`，则允许通过`start_date` 和 `end_date` 指定的最长查询范围为 365 天。</li></ul> |
|query_lifetime | boolean  |仅当 `report_type` 设置为 `BASIC` 或 `PLAYABLE_MATERIAL` 时支持本字段。<br><br>是否请求 Lifetime 指标。<br><br>默认值：`false`。<br><br>若 `query_lifetime` = `true`，将忽略 `start_date` 和 `end_date` 参数。Lifetime 指标名称和普通指标一致。<br><br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>请求 Lifetime 指标时不支持时间细分，或受众维度细分。</li><li>请求 Lifetime 指标时，不支持按地域代码 (`country_code`)细分。</li><li>受众分析报表、DSA 报表、商务中心报表和最大成交额广告报表不支持 Lifetime 指标。</li></ul>|
|multi_adv_report_in_utc_time |boolean| 当请求中使用了`advertiser_ids`时可传入该字段。是否将返回的指标设置为各个广告主的当地时区。默认值：`false`。如果设置为`true`，则将所有广告主返回的指标设置为UTC+0时区。 |
|order_field |string| 排序字段。<br><br>所有支持的指标（不包括属性指标）均支持排序，默认不排序。 |
|order_type |string| 排序方式。<br><br>枚举值: `ASC`（升序），`DESC`（降序）。<br><br> 默认值: `DESC`。|
|filtering|object[]| <ul><li>仅当 `report_type` 设置为 `BASIC`，`AUDIENCE`，`PLAYABLE_MATERIAL`，`CATALOG` 或 `BC` 时支持本字段。 </li><li>`report_type` 设置为 `TT_SHOP` 时不支持本字段。 </li></ul><br>筛选条件。<br><br>支持的筛选条件根据 `service_type` 和 `data_level` 有所不同。了解不同类型报表支持的筛选条件，请参考[报表类型](https://ads.tiktok.com/marketing_api/docs?id=1738864835805186)下的相应文章。<br><br><p><span style="color:darkred"><b>注意</b></span>: <ul><li>当您传入`filtering`字段时, 请确保同时传入 `field_name`, `filter_type`和`filter_value`字段，作为列表中的对象。</li><li>若您想使用`country_code`筛选分组，只需要在请求的`dimensions`字段中指定`country_code`。`country_code`支持基础报表（同步/异步）、受众分析报表（同步/异步）、试玩素材报表（仅同步）和商务中心报表（仅同步）。</li></ul>|
#|field_name{+条件必填} |string| 筛选字段名称。 |
#|filter_type{+条件必填} |string| 筛选类型。<br><br>枚举值：<ul><li>`IN`：包含任意一项（精确匹配）。使用此筛选类型时，筛选值必须是合法的 JSON 数组字符串。 </li><li>`CONTAIN_ANY_OF`：包含任意一项（模糊匹配）。使用此筛选类型时，筛选值必须是合法的 JSON 数组字符串。</li><li>`MATCH`：匹配。此筛选类型相当于 MySQL 中的 `like` 操作，支持模糊匹配。</li><li>`NOT_IN`：不包含任意一项（精确匹配）。使用此筛选类型时，筛选值必须是合法的 JSON 数组字符串。</li><li>`GREATER_EQUAL`：大于等于（简称GE）。</li><li>`GREATER_THAN`：大于（简称GT）。</li><li>`LOWER_EQUAL`：小于等于（简称LE）。</li><li>`LOWER_THAN`：小于（简称LT）。</li><li>`BETWEEN`：介于。使用此筛选类型时，筛选值必须是合法的、包含两个字符串值的 JSON 数组字符串。</li></ul>|
#|filter_value{+条件必填} |string| 要筛选的值。<br><br>当 `filter_type`为`IN`，`CONTAIN_ANY_OF`或`NOT_IN`时，`filter_value` 必须是合法的 JSON 数组字符串。|
|query_mode {-即将废弃}|string| `report_type` 设置为 `BC` 时不支持本字段。<br><br>数据请求模式。<br><br>枚举值：`REGULAR`，`CHUNK`。<br><br>默认值：`REGULAR`。<br><br>开启`CHUNK`模式时，获取报表数据的响应时间会缩短，并且请求更加稳定，同时不支持分页。<br><br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>`CHUNK`模式即将废弃。为保证流畅的 API 体验，不推荐使用该模式。</li><li>`CHUNK`模式仅支持在同步基础报表中使用。</li></ul>|
|page |number| 当前页数。<br><br>默认值: `1`。|
|page_size |number| 分页大小。<br><br>取值范围：1-1000。<br><br>默认值: `10`。|

示例

使用基础报表请求某个升级版 Smart+ 广告组中的广告（素材组）层级数据

(code python)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/report/integrated/get/?advertiser_id={{advertiser_id}}&report_type=BASIC&dimensions=["ad_id_v2","stat_time_day"]&metrics=["campaign_automation_type","ad_name","ad_id_v2","spend","impressions"]&filtering=[{"field_name":"campaign_automation_type","filter_type":"IN","filter_value":"[\"UPGRADED_SMART_PLUS\"]"},{"field_name":"adgroup_ids","filter_type":"IN","filter_value":"[\"{{adgroup_id}}\"]"}]&data_level=AUCTION_AD&start_date=2025-12-03&end_date=2025-12-03&page=1&page_size=1000' \
--header 'Access-Token: {{Access-Token}}'
(/code)

使用基础报表请求某个升级版 Smart+ 广告组中的素材层级数据

(code python)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/report/integrated/get/?advertiser_id={{advertiser_id}}&report_type=BASIC&dimensions=["ad_id","stat_time_day"]&metrics=["campaign_automation_type","ad_name","ad_id","spend","impressions"]&filtering=[{"field_name":"campaign_automation_type","filter_type":"IN","filter_value":"[\"UPGRADED_SMART_PLUS\"]"},{"field_name":"adgroup_ids","filter_type":"IN","filter_value":"[\"{{adgroup_id}}\"]"}]&data_level=AUCTION_AD&start_date=2025-12-03&end_date=2025-12-03&page=1&page_size=1000' \
--header 'Access-Token: {{Access-Token}}' \
(/code)

使用ad_id_v2筛选升级版广告（素材组）的数据

(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/report/integrated/get/' \
--header 'Access-Token: "{{Access-Token}}"' \
--header 'Content-Type: application/json' \
--data '{
    "advertiser_id": "{{advertiser_id}}",
    "service_type": "AUCTION",
    "report_type": "BASIC",
    "data_level": "AUCTION_AD",
    "dimensions": [
        "ad_id_v2"
    ],
    "metrics": [
        "spend",
        "ad_id_v2"
    ],
    "filtering": [
        {
            "field_name": "ad_ids_v2",
            "filter_type": "IN",
            "filter_value": "[\"{{ad_id_v2}}\",\"{{ad_id_v2}}\"]"
        }
    ],
    "start_date": "2025-07-01",
    "end_date": "2025-07-30",
    "page": "1",
    "page_size": "1000"
}'
(/code)

返回

Header

|字段|类型|描述|
|---|---|---|
|X-Tt-Ads-Throttle|string|警告信息：请求超出限制。<br>例如：当查询的广告主账户的广告ID数量超过 20,000 时：`X-Tt-Ads-Throttle:"Number of ad ids is equal or more than 20k, only return the top 20k id's results, sorting by create time desc order."`|

参数

|字段|类型|描述|
|---|---|---|
|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|返回数据。 |
#|total_metrics|object|所有请求指标的汇总数据。 当您在请求中开启 `enable_total_metrics` 参数时，返回此对象。  |
##| campaign_name | string | 竞价广告推广系列名称/合约广告广告组名称。无法聚合的指标（例如，`campaign_name`)的返回值为 `-`。 |
##| spend | string | 消耗的汇总数据。|
##| impressions | string | 广告展现次数的汇总数据。|
##| reach | string | 覆盖人数的汇总数据。  |
##|所有其他指标 | string | 所有其他指标的汇总数据。|
#|list|object[]| 数据列表。 |
##|dimensions|object|所有请求的维度组合数据。|
###|advertiser_id |string|当`dimensions`包含 `advertisre_id` 时返回。<br><br>广告主 ID。|
###|campaign_id |string|当`dimensions`包含 `campaign_id` 时返回。<br><br>推广系列 ID。|
###|adgroup_id |string|当`dimensions`包含 `adgroup_id` 时返回。<br><br>广告组 ID。|
###| ad_id_v2 | string | 当 `dimensions` 包含维度 `ad_id_v2` 时返回。<br><br>广告 ID v2。<br><br>可以从此指标获取的数据类型包括：<ul><li>手动广告的广告层级数据。</li><li>Smart+ 推广系列的广告层级数据。</li><li>升级版 Smart+ 广告的<b>广告</b>层级数据。</li></ul> |
###|ad_id |string|当`dimensions`包含 `ad_id` 时返回。<br><br>广告 ID。<br><br>可以从此指标获取的数据类型包括：<ul><li>手动广告的广告层级数据。</li><li>Smart+ 推广系列的广告层级数据。</li><li>升级版 Smart+ 广告的<b>素材</b>层级数据。</li></ul>|
###|stat_time_day |string|当`dimensions`包含 `stat_time_day` 时返回。<br><br>消耗发生的时间（天）。返回格式：2020-01-01 00:00:00。|
###|stat_time_hour |string|当`dimensions`包含 `stat_time_hour` 时返回。<br><br>消耗发生的时间（小时）。返回格式：2020-01-01 10:00:00。|
###|ac |string|当`dimensions`包含 `ac` 时返回。<br><br>受众网络类型。详见[枚举值-广告管理-网络类型](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
###|age |string|当`dimensions`包含 `age` 时返回。<br><br>受众年龄区间。详见[枚举值-广告管理-受众年龄区间](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
###|country_code|string|当`dimensions`包含`country_code`时返回。<br><br>受众国家或地区代码。详见[附录-地区代码](https://ads.tiktok.com/marketing_api/docs?id=1737585867307010)。|
###| interest_category | string |当`dimensions`包含 `interest_category` 时返回。<br><br>旧版一级兴趣分类。<br><br><p><span style="color:DarkRed"><b>注意</b></span>：旧版一级兴趣分类将在下个 API 版本中废弃。|
###|interest_category_v2|string|当`dimensions`包含 `interest_category` 时返回。<br><br>新版一级兴趣分类。<br><br>使用[/tool/interest_category/](https://ads.tiktok.com/marketing_api/docs?id=1737174348712961)接口获取兴趣分类完整列表。|
###|gender |string|当`dimensions`包含 `gender` 时返回。<br><br>受众性别。枚举值: `FEMALE`，`MALE`，`NONE`。|
###|language |string|当`dimensions`包含 `language` 时返回。<br><br>受众语言。详见[枚举值-广告管理-受众语言](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
###|placement |string|当`dimensions`包含 `placement` 时返回。<br><br>投放版位，详见[枚举值-广告管理-版位](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
###|platform |string|当`dimensions`包含 `platform` 时返回。<br><br>受众操作系统，详见[枚举值-广告管理-受众操作系统](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
###|contextual_tag|string|当`dimensions`中包含`contextual_tag`时返回。<br><br>内容相关定向标签。|
##|metrics|object|所有请求的指标数据。|
###|campaign_name| string | 竞价广告推广系列名称/合约广告广告组名称。|
###|spend|string| 总消耗。 |
###|impressions|string| 广告展现次数。 |
###|reach|string| 覆盖人数。 |
###|所有其他指标|string| 了解不同类型报表支持的指标，请参考[报表类型](https://ads.tiktok.com/marketing_api/docs?id=1738864835805186)下的相应文章。  |
###|advertiser_id |string| 当请求中指定了`advertiser_ids`时返回。<br><br> 广告主ID。 |
###|timezone |string|当请求中指定了`advertiser_ids`时返回。<br><br>广告主时区。 |
###|currency |string|当请求中指定了`advertiser_ids`时返回。<br><br>广告主货币。 |
###| campaign_automation_type | string | 当请求中的 `metrics` 包含 `campaign_automation_type` 指标时返回。<br><br>推广系列自动化类型。<br><br>枚举值：<ul><li>`MANUAL`：手动推广系列。</li><li>`SMART_PLUS`：Smart+ 推广系列。</li><li>`UPGRADED_SMART_PLUS`：升级版 Smart+ 推广系列。要了解有关升级版 Smart+ 推广系列的更多信息，请参阅[升级版 Smart+ 推广系列](1853452461203458.html)。<ul><li>当 `campaign_automation_type` 为 `UPGRADED_SMART_PLUS` 时，返回的 `ad_id_v2` 是升级版 Smart+ 广告的 ID。</li></ul></li><li>`UPGRADED_SMART_PLUS_CREATIVE`：升级版 Smart+ 推广系列。要了解有关升级版 Smart+ 推广系列的更多信息，请参阅[升级版 Smart+ 推广系列](1853452461203458.html)。<ul><li>当 `campaign_automation_type` 为 `UPGRADED_SMART_PLUS_CREATIVE` 时，返回的 `ad_id` 是升级版 Smart+ 广告中素材的 ID。</li></ul></li></ul> |
###| ad_id_v2 | string | 当请求中的 `metrics` 包含 `ad_id_v2` 指标时返回。<br><br>广告 ID v2。<br><br><ul><li>可以从此指标获取的数据类型包括：<ul><li>手动广告的广告 ID</li><li>Smart+ 推广系列的广告 ID</li><li>升级版 Smart+ 广告的广告 ID</li></ul></li></ul> |
###| ad_text_list | string[] | 在满足以下条件时返回：<ul><li>`dimensions` 包含维度 `ad_id_v2` 且 `ad_id_v2` 代表一个升级版 Smart+ 广告。</li><li>请求指标包含 `ad_text`。</li><li>`report_type` 是 `BASIC`、`AUDIENCE` 或 `CATALOG`。</li></ul><br>广告文案列表。 |
###| call_to_action_list | string[] | 在满足以下条件时返回：<ul><li>`dimensions` 包含维度 `ad_id_v2` 且 `ad_id_v2` 代表一个升级版 Smart+ 广告。</li><li>请求指标包含 `call_to_action`。</li><li>`report_type` 是 `BASIC` 或 `AUDIENCE`。</li></ul><br>行动引导文案列表。 |
###| ad_profile_image_list | string[] | 在满足以下条件时返回：<ul><li>`dimensions` 包含维度 `ad_id_v2`。</li><li>请求指标包含 `ad_profile_image`。</li><li>`report_type` 是 `BASIC` 或 `AUDIENCE`。</li></ul><br>广告层级头像图片列表。 |
###| ad_url_list | string[] | 在满足以下条件时返回：<ul><li>`dimensions` 包含维度 `ad_id_v2` 且 `ad_id_v2` 代表一个升级版 Smart+ 广告。</li><li>请求指标包含 `ad_url`。</li><li>`report_type` 是 `BASIC` 或 `AUDIENCE`。</li></ul><br>广告层级 URL 列表。 |
###| image_mode_list | string[] | 在满足以下条件时返回：<ul><li>`dimensions` 包含维度 `ad_id_v2` 且 `ad_id_v2` 代表一个升级版 Smart+ 广告。</li><li>请求指标包含 `image_mode`。</li><li>`report_type` 是 `BASIC` 或 `AUDIENCE`。</li></ul><br>格式列表。 |
###| image_info_list | string[] | 在满足以下条件时返回：<ul><li>`dimensions` 包含维度 `ad_id_v2` 且 `ad_id_v2` 代表一个升级版 Smart+ 广告。</li><li>请求指标包含 `image_info`。</li><li>`report_type` 是 `BASIC` 或 `AUDIENCE`。</li></ul><br>图片列表。 |
###| ad_display_name_list | string[] | 在满足以下条件时返回：<ul><li>`dimensions` 包含维度 `ad_id_v2` 且 `ad_id_v2` 代表一个升级版 Smart+ 广告。</li><li>请求指标包含 `ad_display_name`。</li><li>`report_type` 是 `BASIC` 或 `AUDIENCE`。</li></ul><br>广告显示名称列表。 |
###| identity_type_list | string[] | 在满足以下条件时返回：<ul><li>`dimensions` 包含维度 `ad_id_v2` 且 `ad_id_v2` 代表一个升级版 Smart+ 广告。</li><li>请求指标包含 `identity_type`。</li><li>`report_type` 是 `BASIC` 或 `AUDIENCE`。</li></ul><br>身份类型列表。 |
###| profile_image_list | string[] | 在满足以下条件时返回：<ul><li>`dimensions` 包含维度 `ad_id_v2` 且 `ad_id_v2` 代表一个升级版 Smart+ 广告。</li><li>请求指标包含 `profile_image`。</li><li>`report_type` 是 `BASIC` 或 `AUDIENCE`。</li></ul><br>头像图片列表。 |
#|page_info |object | 分页信息。 |
##|page |number | 当前页数。 |
##|page_size |number | 分页大小。 |
##|total_number |number | 总结果数。 |
##|total_page |number | 总页数。 |

示例

使用基础报表请求某个升级版 Smart+ 广告组中的广告（素材组）层级数据

(code Success-Response http)
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "page_info": {
            "page": 1,
            "page_size": 1000,
            "total_page": 1,
            "total_number": 2
        },
        "list": [
            {
                "dimensions": {
                    // "ad_id_v2" returns ad level data
                    "ad_id_v2": "{{ad_id_v2}}",
                    "stat_time_day": "2025-12-03 00:00:00"
                },

                "metrics": {
                    // ad ID
                    "ad_id_v2": "{{ad_id_v2}}",
                    // ad name
                    "ad_name": "{{ad_name}}",
                    "impressions": "1079",
                    "spend": "14.68",
                    "campaign_automation_type": "UPGRADED_SMART_PLUS"
                }
            },
            {
                "dimensions": {
                    "ad_id_v2": "{{ad_id_v2}}",
                    "stat_time_day": "2025-12-03 00:00:00"
                },
                "metrics": {
                    "ad_id_v2": "{{ad_id_v2}}",
                    "ad_name": "{{ad_name}}",
                    "impressions": "52",
                    "spend": "0.70",
                    "campaign_automation_type": "UPGRADED_SMART_PLUS"
                }
            }
        ]
    }
}
(/code)

使用基础报表请求某个升级版 Smart+ 广告组中的素材层级数据

(code Success-Response http)
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "page_info": {
            "page": 1,
            "page_size": 1000,
            "total_page": 1,
            "total_number": 3
        },
        "list": [
            {
                "dimensions": {
                   // "ad_id" returns creative level data
                    "ad_id": "{{ad_id}}",
                    "stat_time_day": "2025-12-03 00:00:00"
                },
                "metrics": {
                    // creative ID
                    "ad_id": "{{ad_id}}",
                    // creative name
                    "ad_name": "{{ad_name}}",
                    "impressions": "513",
                    "spend": "7.97",
                    "campaign_automation_type": "UPGRADED_SMART_PLUS_CREATIVE"
                }
            },
            {
                "dimensions": {
                    "ad_id": "{{ad_id}}",
                    "stat_time_day": "2025-12-03 00:00:00"
                },
                "metrics": {
                    "ad_id": "{{ad_id}}",
                    "ad_name": "{{ad_name}}",
                    "impressions": "37",
                    "spend": "0.58",
                    "campaign_automation_type": "UPGRADED_SMART_PLUS_CREATIVE"
                }
            },
            {
                "dimensions": {
                    "ad_id": "{{ad_id}}",
                    "stat_time_day": "2025-12-03 00:00:00"
                },
                "metrics": {
                    "ad_id": "{{ad_id}}",
                    "ad_name": "{{ad_name}}",
                    "impressions": "10",
                    "spend": "0.08",
                    "campaign_automation_type": "UPGRADED_SMART_PLUS_CREATIVE"
                }
            }
        ]
    }
}
(/code)

使用ad_id_v2筛选升级版广告（素材组）的数据

(code Success-Response http)
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "page_info": {
            "page": 1,
            "page_size": 2,
            "total_number": 2,
            "total_page": 1
        },
        "list": [
            {
                "dimensions": {
                    "ad_id_v2": "{{ad_id_v2}}"
                },
                "metrics": {
                    "spend": "0.00",
                    "ad_id_v2": "{{ad_id_v2}}"
                }
            },
            {
                "dimensions": {
                    "ad_id_v2": "{{ad_id_v2}}"
                },
                "metrics": {
                    "spend": "186.78",
                    "ad_id_v2": "{{ad_id_v2}}"
                }
            }
        ]
    }
}
(/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 每日平台更新简报 →