← 返回目录
📁 API Reference › Reporting

创建异步报表任务

您可以使用本接口来创建一个异步报表任务。

参阅生成异步报表了解生成异步报表的步骤。

您可以使用不同的接口来创建一个标准（同步）报表和一个异步报表。欲了解不同报表类型支持的维度、指标以及使用案例，请查看报表类型。此外，您需使用POST方法创建异步报表，使用GET方法创建标准（同步）报表。

提示

请查看下表，了解有关频次限制、支持报表类型、查询时间范围、筛选、指标和维度的兼容关系、CHUNK 模式、分页、有效期、数据等的相关提示。

| 类型 {30%}| 详情{70%} |
|---|---|---|
| 频次限制 | 由于计算资源的限制，每个应用程序的速率限制为 1 QPS。请勿频繁创建大量异步报表任务。<br>此外，与您的访问令牌 (`Access-Token`) 关联的用户每小时最多为单个广告账号创建 500 个异步报表。 |
| 支持报表类型 | 异步报表中不支持试玩素材报表。 |
| 查询时间范围 | 异步报表不限制查询起始时间和结束时间，可查询任意合理时间范围内的数据。 |
| 筛选 | <ul><li>异步报表只支持通过 `campaign_ids `、 `adgroup_ids `、 `ad_ids `、 `country_code `进行筛选。最多可以通过20000个ID来筛选数据。</li><li>如果您想使用`country_code`筛选分组，只需要在请求的`dimensions`字段中指定`country_code`。`country_code`适用于基础报表（同步和异步），受众分析报表（同步和异步）和试玩素材报表（仅同步）。</li></ul> |
| 指标和维度的兼容关系 | <ul><li>异步报表不支持查询UV类指标在受众维度下的数据。请在异步报表中仅查询UV类指标在非受众维度下的数据，或受众维度下非UV类指标的数据。<ul><li>受众维度包括:<code>"gender"</code>， <code>"age"</code>， <code>"country_code"</code>， <code>"ac"</code>， <code>"language"</code>， <code>"platform"</code>， <code>"interest_category"</code>， <code>"placement"</code>， <code>"contextual_tag"</code>。</li><li>UV类指标包括：<code>"average_video_play_per_user"</code>， <code>"frequency"</code>， <code>"cost_per_1000_reached"</code>， <code>"real_time_result"</code>， <code>"real_time_result_rate"</code>， <code>"real_time_cost_per_result"</code>， <code>"result"</code>， <code>"result_rate"</code>， <code>"cost_per_result"</code>， <code>"reach"</code>， <code>"live_play_count"</code>。</li></ul></li><li>同步报表和异步报表中支持的维度和指标组合可能不同，因此同步报表中支持的维度和指标组合可能在异步报表中不支持。</li></ul> |
| CHUNK模式 | CHUNK模式仅支持同步基础报表。 |
| 分页 | 不支持分页。 |
| 有效期 | 异步报表任务的有效期为30天，之后您不能查询其状态和任务结果。 |
| 数据 | 异步报表的数据每几个小时刷新一次。请求当天的数据可能不准确。 |
| 已知问题 | 目前，异步报表中的`country_code `维度（例如`US`）会返回 `country_name`（例如 `United States`）。该问题将在后续更新中修复。 |

v1.2与v1.3版本对比

以下表格概括了 v1.2与v1.3接口的变化。 ``xtable |变化内容{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| | 接口路径 |/v1.2/reports/integrated/get/ <br>(POST方法) | /v1.3/report/task/create/ <br>(POST方法) | | 请求参数名称 |filters|filtering| | 请求参数类型 |advertiser_id: number |advertiser_id: string | | 废弃请求参数| / |lifetime（由新请求参数query_lifetime替代） | | 新增请求参数| / |output_format<br>file_name<br>query_lifetime<br>advertiser_ids<br>enable_report_title_translation`| |维度| / | 了解不同类型报表类型支持的维度的变动，请参考报表类型下的相应文章。 |指标| / | 了解不同类型报表类型支持的指标的变动，请参考报表类型下的相应文章。


## 请求

**请求地址** https://business-api.tiktok.com/open_api/v1.3/report/task/create/

**请求方法** POST

**Header**

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

参数

|字段|类型|描述|
|---|---|---|
|advertiser_id {+条件必填}|string| `advertiser_id` 和`advertiser_ids` 必传其一。若您同时传入`advertiser_id`和`advertiser_ids`，将忽略`advertiser_id`字段。<br><br>广告主ID。 |
| advertiser_ids{+条件必填} | string[] | `advertiser_id` 和`advertiser_ids`必传其一。若您同时传入`advertiser_id`和`advertiser_ids`，将忽略`advertiser_id`字段。<br><br>广告主ID列表。<br>最大数量：5。 <br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>本字段仅当 `report_type`为`BASIC`或`AUDIENCE`时生效。</li><li>`advertiser_ids`中指定的广告主应属于同一个TikTok for Business用户。否则会出错。使用[/oauth2/advertiser/get/](1738455508553729.html)接口来获取同一个TikTok for Business用户的广告主ID列表。</li><li>若您还同时传入了`start_date` 和 `end_date` ，会根据每个广告账户的时区拉取数据。</li><li>若您传入多个广告主ID，您可在`dimensions`字段设置最多两个ID维度（`advertiser_id`和另一 ID 维度）。不过，很多指标不支持在`advertiser_id` 维度下使用。同时，推荐您在`metrics`的值中设置`currency`，因为不同广告账号的币种可能不同。</li></ul>|
|service_type |string| 广告服务类型。<ul><li>`AUCTION`：竞价广告，或竞价和合约广告。</li><li>`RESERVATION`（<span style="color:Red">已废弃</span>）：合约广告。 </li></ul> 默认值: `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| 报表类型。枚举值：`BASIC`（基础报表），`AUDIENCE`（受众分析报表），`PLAYABLE_MATERIAL` （试玩素材报表），`CATALOG`（DSA报表） 。<br><br>当 `service_type` 为 `AUCTION`时, 所有报表类型（`BASIC`，`AUDIENCE`，`PLAYABLE_MATERIAL`，`CATALOG`）均支持。<br><br><p><span style="color:darkred"><b>注意</b></span>：当 `report_type` 为 `BASIC`、`AUDIENCE` 或 `CATALOG` 时，您可以检索升级版 Smart+ 广告的素材层级数据。</p>  |
|data_level {+条件必填} |string| 您想要查询的报表数据层级。当`report_type`为 `BASIC`、`AUDIENCE` 或 `CATALOG` 时必填。<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>|
|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></ul> <br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>不同报表类型支持的维度不同，了解不同报表类型支持的维度组合，请参考[报表类型](https://ads.tiktok.com/marketing_api/docs?id=1738864835805186)下的相应文章。</li><li>若您查询的`dimensions`中不只包含 xx_id 且查询时间范围内没有广告报表，会返回空列表。</li><li>同步报表和异步报表中支持的维度和指标组合可能不同，因此同步报表中支持的维度和指标组合可能在异步报表中不支持。</li><li>可使用维度 `ad_id_v2`。请注意：<ul><li>需要确保 `report_type` 是 `BASIC`、`AUDIENCE` 或 `CATALOG`。</li><li>不能将其与维度 `ad_id` 或筛选条件 `ad_ids` 一起使用。</li><li>可以获取的数据类型包括：<ul><li>手动广告的广告层级数据。</li><li>Smart+ 推广系列的广告层级数据。</li><li>升级版 Smart+ 广告的广告层级数据。</li></ul></li></ul></li></ul></ul>|
|metrics |string[]|  要查询的指标。不同报表类型支持的指标不同。了解不同类型报表支持的指标，请参考[报表类型](https://ads.tiktok.com/marketing_api/docs?id=1738864835805186)下的相应文章。<br>默认值：`&#91;"spend", "impressions"&#93;`。|
|start_date {+条件必填} |string|若`query_lifetime` 未传入或设置为`false`，则本字段必填。<br><br>查询起始日期（闭区间），格式为`YYYY-MM-DD`。日期根据广告主时区设定。<br><br><p><span style="color:darkred"><b>注意</b></span>：异步报表无查询时间范围限制。|
|end_date {+条件必填} |string|  若`query_lifetime` 未传入或设置为`false`，则本字段必填。<br><br>查询结束日期（闭区间），格式为`YYYY-MM-DD`。日期根据广告主时区设定。<br><br><p><span style="color:darkred"><b>注意</b></span>：异步报表无查询时间范围限制。 |
|query_lifetime | boolean  |是否请求 Lifetime 指标。默认值：`False`。若 `query_lifetime` = `True`，将忽略 `start_date` 和 `end_date` 参数。Lifetime 指标名称和普通指标一致。<br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>请求 Lifetime 指标时不支持时间细分，或受众维度细分。</li><li>请求 Lifetime 指标时，不支持按地域代码 (`country_code`) 细分。</li><li>DSA 报表不支持 Lifetime 指标。受众分析报表暂不支持 Lifetime 指标，预计在2023 上半年支持。</li></ul>|
|order_field |string| 排序字段。所有支持的指标（不包括属性指标）均支持排序，默认不排序。 |
|order_type |string| 排序方式。枚举值: `ASC`（升序），`DESC`（降序）。 默认值: `DESC`。|
| enable_report_title_translation | boolean | 是否启用异步报表标题行（包括维度名称和指标名称）的翻译。<br>若本字段设置为`false`，则将显示未翻译的标题（例如`ad_id`）而非翻译过的标题（例如`AD ID`）。<br>默认值：`true`。<br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>本字段仅当`report_type`为`BASIC`或`AUDIENCE`时生效。</li><li>自 2024 年 11 月 15 日起，将更新异步报表标题行中某些指标的翻译，以提供更好的用户体验。这一变更不会影响指标字段本身的名称。为了最大限度地减少潜在影响，强烈建议在您的代码中将 `enable_report_title_translation` 设置为 `false`。这将消除代码对指标翻译的依赖，避免指标翻译的定期更新带来的影响。虽然指标翻译可帮助您将指标映射到 TikTok 广告管理平台中的对应报表指标，但在代码中依赖指标翻译可能会在未来引发重大变更。通过禁用标题行翻译，您可以确保您的集成更加稳定、可靠。</li></ul> |
| output_format | string | 输出格式。 枚举值：`CSV_STRING`，`CSV_DOWNLOAD`，`XLSX_DOWNLOAD`。默认值：`CSV_STRING`。|
|file_name| string | 自定义下载文件名称。当`output_format`为`CSV_DOWNLOAD`或`XLSX_DOWNLOAD`时，可选择传入。最多可传入255个字符，文件名称不能包含以下特殊符号：['/', '\t', '\b', '@', '#', '$', '%', '^', '&', '*', '(', ')', '[', ']']。|
|filtering|object[]| 筛选条件。支持的筛选条件根据 `service_type` 和 `data_level` 有所不同。了解不同类型报表支持的筛选条件，请参考[报表类型](https://ads.tiktok.com/marketing_api/docs?id=1738864835805186)下的相应文章。<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><li>异步模式下的基础报表，受众分析报表、DSA报表和合约广告报表仅支持`campaign_ids`，`adgroup_ids`和`ad_ids`为筛选条件。 </li></ul>|
#|field_name|string| 筛选字段名称。<br><br>可使用筛选条件 `ad_ids_v2` 。请注意：<ul><li>不能将其与维度 `ad_id` 或筛选条件 `ad_ids` 一起使用。</li><li>可以筛选的 ID 类型包括：<ul><li>手动广告的 ID。</li><li>Smart+ 推广系列中广告的 ID。</li><li>升级版 Smart+ 广告的 ID。</li></ul></li><li>需要将 `data_level` 设置为 `AUCTION_AD` 并在 `dimensions` 中包含 `ad_id_v2`。</li><li>使用此筛选条件时，最多可以指定 100 个值。</li></ul> |
#|filter_type |string| 筛选类型。枚举值：<ul><li>`IN`：包含，当筛选类型为此项时，筛选的值必须是合法的JSON数组字符串。</li><li>`MATCH`：模糊匹配，相当于 MySQL 中的`like` 操作。</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><br>当 `field_name` 为 `ad_id_v2` 时，将 `filter_type` 设置为 `IN`。|
#|filter_value |string| 要筛选的值。当 `filter_type`为`IN` 时，`filter_value` 必须是合法的JSON数组字符串。|

示例

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/report/task/create/' \
--header 'Access-Token: {{access-token}}' \
--data-raw '{
    "advertiser_id": "{{advertiser_id}}",
    "data_level":"AUCTION_AD",
    "report_type":"BASIC",
    "dimensions": ["ad_id"],
    "metrics": ["clicks"],
    "start_date": "{{start_date}}",
    "end_date": "{{end_date}}",
    "output_format": "CSV_DOWNLOAD",
    "file_name": "{{file_name}}",
    "filtering": [
        {
        "field_name":"ad_ids",
        "filter_type":"IN",
        "filter_value": "[\"{{ad_id}}\",\"{{ad_id}}\"]"
        }
    ]
}'
(/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|返回数据。 |
#|task_id |string| 异步报表任务ID。 |
|request_id |string|请求的日志ID，唯一标识一个请求。  |

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "data": {
        "task_id": "{{task_id}}"
    },
    "request_id": "{{request_id}}"
}
(/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 每日平台更新简报 →