常见问题

本文总结了使用报表管理API时的常见问题。

数据不一致

Q1: 我注意到 API 报表和 TikTok 广告管理平台的报表之间存在数据不一致，为什么会出现这种情况？
数据不一致可能有几大原因。在寻求帮助之前，请检查以下可能性： - 不同的报表类型和维度：API报表类型与TikTok广告管理平台上的类型不同。例如，API 报表类型为基础报表，而 TikTok 广告管理平台上为“Catalog/DPA”报表，因为TikTok广告管理平台上的报表包括“产品名称”或其他列，使其成为“Catalog/DPA”报表。
此外，还需注意TikTok广告管理平台的“查看数据”标签页展示的数据和API报表的数据之间可能存在不一致。因为“查看数据”标签页为每个广告主无对应数据的指标展示0的值，但API报表中一些无数据的指标会筛选掉。所以，和TikTok广告管理平台的“查看数据”标签页展示的数据相比，API报表的广告数据可能较少。
- 不同维度下的数据延迟：不同维度下的数据延迟是不同的。例如，如果你在基础报表中使用维度国家代码，数据延迟大约为11小时，但不使用该维度时，数据延迟为30分钟。请查看报表数据延迟，获取更多详细信息。 - 不同的筛选条件：确保通过API和TikTok广告管理平台使用的筛选条件相同。例如，campaign_status、adgroup_status和ad_status的筛选条件默认为STATUS_NOT_DELETE，若您想查询所有广告（包括已删除的广告），可以将相应的API筛选条件更改为STATUS_ALL以包括所有状态。 - 不同的数据级别：通常因比较不同级别的数据造成。例如，API报表是推广系列级别，但您正在查看和比较TikTok广告管理平台上的广告级别。你可以使用Reporting API中的dimension字段选择级别。 - 不同的请求时间：API和TikTok广告管理平台上的报表请求时间不同。若您想获取前一天的准确数据，建议在8:00（UTC+0）之后拉取数据，因为每天8:00（UTC+0）会执行数据修复脚本。 - 页面大小：API返回中可能包含多个页面。若您发现通过/report/integrated/get/接口获取的数据比从TikTok广告管理平台中获取的数据少，原因之一可能是page_size（页面大小）不够大。在这种情况下，将page_size设置为更大的数字。

Q2: 为什么请求成功但并没有返回数据？例如，返回中的list对象为[]。
可能是由于以下原因： - API报表没有返回所有广告。若您的广告主在请求指定的时间段内（开始日期和结束日期）广告主停止在TikTok上的广告投放，则我们只会返回活动广告的数据。 - 请求中的 service_type 与您的广告主账户类型不匹配，报告将返回 200 的成功代码，但数据列表为空（[]）。举个例子，如果您的广告主账户类型是 RESERVATION，但在运行报告时指定了 AUCTION作为服务类型，那么结果将是一个空的数据列表。

Q3: 为什么API报表似乎返回了和实际创建的广告数相比，更多的广告数据？
可能是由于以下原因： - API报表为（通过start_date和 end_date）指定的时间区间内创建的广告的指标返回了实际数据，并为end_date日期后创建的广告的指标返回数值0。例如，若您在2023年5月1日和2023年5月3日间创建了20个广告，随后在2023年5月4日创建了10个广告，当您在2023年5月4日请求API报表时，您可能会获取到30个广告，而非20个广告的数据。 此不一致不会影响请求指标的数据，因为额外的10个广告的指标数据均为0。

Q4: 为什么API报表似乎返回了和实际创建的广告数相比，更少的广告数据？
可能是由于以下原因： - API报表筛选掉了一些无花费的广告（请注意广告是否有花费通过内部算法决定）。例如，若您创建了10个广告，其中4个无花费，那么当您通过API报表拉取数据时，您可能只能拉取到8个广告的数据。这是因为其中2个无花费的广告已筛选掉，而剩余的2个无花费的广告的指标均默认设置为了0。

Q5: 对于无对应报表数据的推广系列，例如推广系列中无在投广告时，为什么同步报表接口/report/integrated/get/有时返回数值0，但有时又返回空的列表？
可能是由于以下原因： - 同步报表接口/report/integrated/get/对于无指标数据的情况，有时返回数值0，有时返回空的list对象，这是受历史设计影响。例如，当dimensions字段中包含了stat_time_day 时，返回中可能返回空list对象，因为无数据的指标均已筛选掉。此筛选机制主要用于表明所请求的指标无对应数据。这两种处理方法传递了相同的讯息，即无对应的报表数据。

Q6: 在受众报表中使用province_id维度时，为什么返回的数据不完整，而且与 TikTok 广告管理平台上请求“二级地区”维度时的数据不一致？

受众报表中使用province_id维度时，会筛除一些地域 ID 对应的报表数据，从而造成数据不完整。而 TikTok 广告管理平台上的“二级地区”维度，则会返回所有地域 ID 对应的报表数据。此数据不一致为已知问题，后续将进行修复。在修复完成前，若您希望获取完整的二级地区细分数据，推荐您在 TikTok 广告管理平台上请求“二级地区”维度。

Q7: 在同步报表中使用兴趣定向相关维度时，为什么返回的数据不完整，而且与 TikTok 广告管理平台上请求“兴趣”维度时的数据不一致？

同步报表中使用interest_category, interest_category_tier2, interest_category_tier3, interest_category_tier4维度时，会筛除一些兴趣定向对应的报表数据，从而造成数据不完整。API目前不支持所有的兴趣定向。若您希望获取完整的兴趣定向细分数据，推荐您在 TikTok 广告管理平台上请求“兴趣”维度。

数据延迟

Q1: 现在报表数据延迟的详细情况是什么？ * 参见报表数据延迟。

维度和指标

Q1: 哪里可以找到不同维度下支持的指标？

点击以下文档链接，可以找到基础报表，受众分析报表，试玩素材报表和商务中心报表中维度支持的指标。

Q2: 调用/report/integrated/get/接口时，我收到了“Conflict occurs. The input params including metrics and dimensions have no relation.”的报错信息。可能的原因是什么?

可能您在请求中指定的数据级别、维度或指标之间存在冲突。例如，如果您的广告账户正在运行行动推广系列，则data_level不能为 RESERVATION_XXX。若您想检查不同报表类型维度下支持的指标，请查看基础报表，受众分析报表，试玩素材报表和商务中心报表。

生成报表

Q1: 是否支持一次性为多个广告账户请求报表？ * 不支持，每次只能为一个广告账户请求报表，且广告主ID需要和推广序列，广告组和广告ID匹配。

Q2：请求报表时，请求中时间以哪个时区为准？ * 请求参数中的start_date和 end_date 的时区基于广告账户所在的时区，create_time的时区默认为UTC+0。 * 使用筛选项字段create_time（filter_name=create_time）时，需要考虑广告账户所在的时区与UTC时间之间的时间差。广告主将获取UTC时间转换成的本地时间区间的报表数据 （请求中的时间 + 广告账户所在的时区与UTC时间的时间差 ） 。例如，若账户时区为UTC-8，需要筛选出当地时间7月1号15：00后的数据，则需将create_time设置为7月1号23：00以UTC时间进行请求。

数据不完整

Q1: 同步报表的20,000条数据截断问题是什么？ * 问题: 报表接口会检查当前账号下广告是否超过20,000条。当一次查询的报表涉及广告个数超过20,000时，按创建时间倒序获取20,000个广告的数据，然后通过聚合条件把聚合后的数据中带消耗的数据返回给用户。
此时返回的Header中将会显示：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."

例如，若您请求30,000条广告的数据，其中2,000条带消耗，您可能最终收到1,356条广告（即少于2,000条）的数据。这是因为：

1. 触发了20,000条数据截断，导致仅最近的20,000条广告的数据被处理。某些带消耗的数据可能属于遭截断的10,000条数据，因而没有返回。
2. 在剩余的20,000条未截断的广告中，仅返回带消耗数据的广告（在此示例中为1,356条），同时筛除无消耗数据的广告（在此示例中为8,644条）。需注意，总消耗指标大于0仅为具有消耗数据的前提条件之一。

• 广告属于被截断的10,000条广告，无论它是否具有消耗数据。
• 广告未被截断，但由于无消耗数据数据而在返回之前被筛除。

注意
若您将同步报表的数据与从 TikTok 广告管理平台下载的报表对比，您会发现数据不一致，因为 TikTok 广告管理平台下载的报表数据对应异步报表的数据，而非同步报表的数据。TikTok 广告管理平台的下载报表与API中的异步报表均不进行20,000条数据截断。 * 解决方法: 若您请求同步报表时发现返回的Header中显示x-tt-ads-throttle，意味着此时触发了20,000条数据截断，您可以在filtering字段指定更细化的筛选条件筛选数据。例如，若您请求同步基础报表时，过滤条件设置为ad_status = STATUS_ALL以获取所有广告，返回中出现x-tt-ads-throttle, 您可以将筛选条件更改为adgroup_ids，从而缩小报表数据的范围。

数据限制

Q1:从报表接口中能够获取的数据有哪些时间范围限制?

• 对于同步报表，能够获取的数据的时间范围限制为：

  • 如果请求按小时划分的数据，最多能获取24小时的数据。
  • 如果请求按天划分的数据，最多能获取30天的数据。
  • 其他情况下，最多能获取365天的数据。

• 对于异步报表，获取数据没有时间范围限制。

Q2: 异步报表的频控规则是什么?

• 对于异步报表，每个应用程序的速率限制为1 QPS，每个应用程序每天的最大任务数为4500个。
• 获取异步报表详细信息，请参阅异步报表。
• 获取最佳实践，请参阅最佳实践。

Q3: 广告报表的数据保留期是多久？

• 报表数据永久保留，没有查询回溯范围的限制。

受众报表

Q1: 兴趣分类的层级（1,2,3,4级）是否为树形结构？同一账户ID下，各层级的兴趣分类数据能否在受众分析报表中向上进行汇总？ * 兴趣分类的层级遵循树形结构。 * 受众分析报表中各层级的兴趣分类数据可以向上汇总。例如属于相同1级兴趣分类的2级兴趣分类数据可以汇总成对应的1级兴趣分类数据。

创意素材表现数据

Q1: 为什么我使用 /report/video_performance/get/接口获取我的65秒视频的表现数据，只返回了60秒的数据？ * 目前该接口只支持最多返回60秒的数据，超过60秒的数据将归到第60秒。

Q2: 报表管理API与创意报表API的区别是什么？ - 下表总结了报表管理与创意报表在三个方面的差异对比：

• 接口数量。 报表管理共有4个接口，您可以使用报表管理接口创建同步报表（需使用/report/integrated/get/），创建异步报表任务 (需使用/report/task/create/)，获取异步报表任务状态（需使用/report/task/check/），和下载异步报表（需使用/report/task/download/）。
  获取创意报表则只需调用唯一的创意报表接口/creative/report/get/。
• 支持数据维度。创建同步报表或异步报表时，您可以通过data_level字段指定数据层级为推广系列层级，广告组层级，广告层级，或广告账户层级。创意报表的数据层级则默认均为创意素材层级，您可通过material_type字段指定报表对应的素材类型为VIDEO，IMAGE或INSTANT_PAGE。
• 是否支持数据分组。使用报表管理接口/report/integrated/get/或/report/task/create/创建报表时，您可通过dimensions字段设置数据分组维度。例如，基础报表支持的分组维度包括：advertiser_id, campaign_id, adgroup_id, ad_id, stat_time_day, stat_time_hour和country_code。创意报表接口/creative/report/get/则不支持数据分组。

其他

Q1: /ad/get/接口的返回中只有 app_name字段，没有 app_id 。应用管理接口只返回app_id，但不返回 ad_id 。这两个接口的app信息怎么关联起来? * 通过/ad/get/接口的返回获取app_name后，可以使用 /adgroup/get/接口获取app_id。随后将app_id 传递给/app/info/接口，返回中也得到app_name，两个接口的应用信息便实现关联。