← 返回目录
📁 Marketing API › Reporting › Guides › Report types › Basic reports

支持的筛选条件

您可以使用以下筛选条件缩小报表的范围。

在您开始之前，请阅读下列注意事项：

  • 传递多个筛选条件时，筛选条件间是 AND 的关系。
  • 当使用 IN 筛选类型时，filter_value必须是合法的 JSON 列表字符串。
    示例："[\"ID1\",\"ID2\",\"ID3\"]"。
  • 当使用 BETWEEN 筛选类型时，filter_value必须是合法的、包含两个元素的 JSON 数组字符串。
    示例："[\"2022-02-24 11:57:51\",\"2022-03-24 11:57:51\"]"。
  • 获取代码示例，请参阅基础报表-使用案例。

注意
- 若指定的筛选字段 field_name 和 data_level 不匹配，系统将返回报错："Invalid value for filter field: xxxx is not supported"。例如，若 data_level 为 AUCTION_AD，仅支持将 field_name 设置为广告层级的筛选字段（例如 ad_ids）。 - 异步基础报表中仅支持campaign_ids，adgroup_ids和ad_ids为筛选条件。 - 基础报表现在包括竞价广告、覆盖和频次广告以及 TopView 广告数据。要筛选特定售卖类型的数据，请使用 /report/integrated/get/ 生成基础报表。在filtering对象数组中，指定buying_type字段并输入AUCTION、RESERVATION_TOP_VIEW或RESERVATION_RF枚举值。 - 对于 TopView 广告，仅支持为 2024 年 1 月 18 日后投放的广告拉取广告层级消耗相关的指标及受众细分的消耗相关的指标数据。 - 同步竞价基础报表、受众分析报表、试玩素材报表和 DSA 报表中不包含通过 TikTok Shop 创建的商品最大成交额广告（Product GMV max ads）和直播商品交易总额最大化广告（LIVE GMV max ads）的报表数据。通过 API 或 TikTok 广告管理平台创建的购物广告则不受影响。

| 筛选字段 {22%} | 支持的筛选类型 {13%} | 支持的广告层级 {18%} | 备注 {47%} |
| --- | ---| --- | ---|
| campaign_ids | IN | 推广系列、广告组、广告| 推广系列ID，使用此筛选条件时，最多可传入100 个 `campaign_id`。筛选值示例：`"[123, 456, 789]"` 。|
| campaign_automation_type | IN | 推广系列/广告组/广告 | 推广系列自动化类型。<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></ul> |
| campaign_system_origins | IN | 推广系列、广告组、广告 | 推广系列来源。<br><br>枚举值：<ul><li>`PROMOTE`：该推广系列为通过 TikTok 移动应用创建的内容加热推广系列。</li><li>`TT_ADS_PLATFORM`：该推广系列为通过 API 或 TikTok 广告管理平台创建的非内容加热推广系列。</li></ul><br> 默认值：`"&#91;\"TT_ADS_PLATFORM\"&#93;"`。<br><br>若想了解内容加热广告支持的维度、指标和筛选条件，请查看[内容加热推广系列](1785880454546433.html)。    <br><br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>仅支持在同步基础报表中使用本筛选条件。</li><li>异步基础报表中默认返回内容加热广告的报表数据。</li></ul>   |
| adgroup_ids | IN | 广告组、广告 | 广告组ID，使用此筛选条件时，最多可传入100 个 `adgroup_id`。|
| ad_ids_v2 | IN | 广告 | <ul><li>可以筛选的 ID 类型包括：<ul><li>手动广告的 ID。</li><li>升级版 Smart+ <b>广告</b>（<b>素材组</b>）的 ID。</li></ul></li><li>需要将 `data_level` 设置为 `AUCTION_AD` 并在 `dimensions` 中包含 `ad_id_v2`。</li><li>使用此筛选条件时，最多可以指定 100 个值。</li><li>不能将此筛选条件与维度 `ad_id` 或筛选条件 `ad_ids` 一起使用。</li></ul> |
| ad_ids | IN | 广告 | 广告ID，使用此筛选条件时，最多可传入100 个`ad_id`。 |
| campaign_status | IN | 推广系列 | 推广系列状态，枚举值见[枚举值-广告管理-一级状态](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138) 。<br><p><span style="color:darkred"><b>注意</b></span>：同步基础报表中若未设置此筛选条件字段，则此字段默认设置为`STATUS_NOT_DELETE`。|
| adgroup_status | IN | 广告组 | 广告组状态，枚举值见[枚举值-广告管理-一级状态](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138) 。<br><p><span style="color:darkred"><b>注意</b></span>：同步基础报表中若未设置此筛选条件字段，则此字段默认设置为`STATUS_NOT_DELETE`。|
| ad_status | IN | 广告 | 广告状态，枚举值见[枚举值-广告管理-一级状态](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138) 。<br><p><span style="color:darkred"><b>注意</b></span>：同步基础报表中若未设置此筛选条件字段，则此字段默认设置为`STATUS_NOT_DELETE`。|
| campaign_label_ids | IN、NOT_IN | 推广系列、广告组、广告 | 推广系列标签 ID 列表。<br><br>最大数量：50。<br><br>每个标签 ID 必须为 19 位数字字符串。<br><br><p><span style="color:darkred"><b>注意</b></span>：本筛选条件仅支持在同步报表中使用。</p> |
| campaign_label_names | CONTAIN_ANY_OF | 推广系列、广告组、广告 | 推广系列标签名称列表。<br><br>支持模糊匹配。<br><br>最大数量：10。<br><br><p><span style="color:darkred"><b>注意</b></span>：本筛选条件仅支持在同步报表中使用。</p> |
| campaign_label_types | IN、NOT_IN | 推广系列、广告组、广告 | 推广系列标签类型列表。<br><br>枚举值：<ul><li>`GENERAL`：通用标签。</li><li>`MARKETING_EVENT`：营销事件标签。</li></ul><br><p><span style="color:darkred"><b>注意</b></span>：本筛选条件仅支持在同步报表中使用。</p> |
| objective_type | IN | 推广系列、广告组、广告 | 推广目标<br>枚举值：`APP_PROMOTION`, `APP_INSTALL`, `CONVERSIONS`, `REACH`，`BRAND_CONSIDERATION`，`TRAFFIC`, `VIDEO_VIEWS`, `PRODUCT_SALES`, `ENGAGEMENT`, `LEAD_GENERATION`, `CATALOG_SALES`, `SHOP_PURCHASES`。|
| billing_event | IN | 推广系列、广告组、广告 | 计费事件。 枚举值：详见[枚举值-计费事件](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138#item-link-%E8%AE%A1%E8%B4%B9%E4%BA%8B%E4%BB%B6) 。 |
| age | IN | 推广系列、广告组、广告 | 受众年龄区间。<br>枚举值可见枚举值-[受众年龄区间](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。 |
| gender | IN | 推广系列、广告组、广告 | 受众性别。<br>枚举值： `GENDER_FEMALE`, `GENDER_MALE` |
| dpa_target_audience_type | IN | 推广系列、广告组、广告| DPA广告的受众类型。枚举值： `RETARGETING`, `PROSPECTING`。本筛选条件只能用于同步报表中。 |
| buying_type | IN | 推广系列、广告组、广告 | 售卖类型。 <br>枚举值：`AUCTION`, `RESERVATION_TOP_VIEW`, `RESERVATION_RF`. |
| is_cbo_enabled | IN | 推广系列、广告组、广告 | 推广系列预算优化。<br>枚举值：`CBO_CAMPAIGN`, `NON_CBO_CAMPAIGN`。 |
| app_promotion_type | IN | 推广系列、广告组、广告 | 应用推广类型。<br>枚举值：<br>`APP_INSTALL`: 应用安装。让新用户安装您的应用。<br>`APP_RETARGETING`: 应用再营销。重新吸引现有用户在您的应用中执行操作。 |
| campaign_product_source | IN | 推广系列、广告组、广告 | 推广系列的商品来源。<br> 枚举值：<ul><li> `CATALOG` ：商品库。</li><li>`STORE`：TikTok Shop 店铺，或 TikTok 橱窗。</li></ul>|
|optimization_goal| IN|推广系列、广告组、广告|优化目标。获取枚举值，请参阅[枚举值 - 优化目标](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138#item-link-优化目标)。|
| promotion_type | IN | 推广系列、广告组、广告 | 推广对象类型（优化位置）。<br><br>枚举值：<ul><li>`APP`：应用。</li><li>`WEBSITE`：落地页。</li><li>`INSTANT_FORM`：线索表单（即时表单）。</li><li>`LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE`：TikTok 私信。</li><li>`LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE`：即时通讯应用。</li><li>`LEAD_GEN_CLICK_TO_CALL`：电话通话。</li><li>`OTHERS`：其他。</li></ul><br>本筛选条件只能用于同步报表中。|
|bid_strategy|IN|推广系列、广告组、广告|竞价策略。枚举值：`BID_STRATEGY_COST_CAP`, `BID_STRATEGY_BID_CAP`, `BID_STRATEGY_MAX_CONVERSION` `BID_STRATEGY_LOWEST_COST`，`BID_STRATEGY_HIGHEST_VALUE`, `BID_STRATEGY_GMV` 和 `BID_STRATEGY_MINIMUM_ROAS` |
| delivery_type | IN | 推广系列、广告组、广告 | 投放方式（投放速度）.<br>枚举值：`PACING_MODE_SMOOTH`, `PACING_MODE_FAST` |
| ad_entity_type | IN | 推广系列、广告组、广告 | 广告类型。<br>枚举值：<br>`VIDEO_SHOPPING_ADS`, `LIVE_SHOPPING_ADS`, `CATALOG_LISTING_ADS`, `PRODUCT_SHOPPING_ADS` |
| identity_type | IN | 推广系列、广告组、广告 | 认证身份类型。<br>枚举值：`TT_ACCOUNT`, `CUSTOM_IDENTITY` |
| image_mode | IN | 广告 | 素材样式。 <br>枚举值： <ul><li>`IMAGE_MODE_LARGE`：图片</li><li>`IMAGE_MODE_VIDEO`：视频(16:9) </li><li> `IMAGE_MODE_VIDEO_SQUARE`：视频(1:1)</li><li>`IMAGE_MODE_VIDEO_VERTICAL`：视频(9:16) </li><li>`CAROUSEL_ADS`: 轮播。</li></ul><p><span style="color:darkred"><b>注意</b></span>：本筛选条件仅支持在同步基础报表中使用。 |
|creative_material_mode|IN|广告组、广告|创意投放方式。<br>枚举值: `CUSTOM`（自定义）、`DYNAMIC`（程序化）、`SMART_CREATIVE`（智能创意）。|
| destination | IN | 广告 | 目标页面类型。<br>枚举值：<ul><li>`APP`：所推广App在Google Play或Apple Store的下载页面。广告对应的广告组中`promotion_type` 设置为 `APP_ANDROID` 或 `APP_IOS`。</li><li>`TIKTOK_INSTANT_PAGE`: TikTok即时体验页面，包括自定义页面、线索表单（即时体验表单）、应用介绍页和即时体验商品页面。广告中指定了 TikTok 即时体验页面的页面 ID（`page_id`）。</li><li> `WEBSITE`：网站页面。广告中指定了落地页（`landing_page_url`）。</li><li>`SOCIAL_MEDIA_APP`：社交媒体 URL。若想了解支持将目标页面设置为社交媒体 URL 的广告类型，请查看[创建推广对象类型为即时通讯应用的线索广告](1774482999036930.html)。 </li><li> `PHONE_CALL`：电话号码。若想了解支持将目标页面设置为电话号码的广告类型，请查看[创建推广对象类型为电话通话的线索广告](1774482936048641.html)。</li></ul><br><p><span style="color:darkred"><b>注意</b></span>：本筛选条件仅支持在同步基础报表中使用。 |
| campaign_type | IN | 推广系列、广告组、广告 | 推广系列类型。枚举值：`REGULAR_CAMPAIGN`（普通推广系列），`IOS14_CAMPAIGN`, `IOS14_CAMPAIGN_WITH_APP_PROFILE_PAGE`, `IOS14_CAMPAIGN_WITHOUT_APP_PROFILE_PAGE`。|
|creative_campaign_type| IN | 推广系列、广告组、广告 | 按推广系列是否为 Smart+ 推广系列、搜索广告推广系列、或非 Smart+ 且非搜索广告类型的推广系列筛选。<br><br>枚举值： <ul><li>`SMART+`：仅获取 Smart+ 推广系列。</li><li>`SEARCH_CAMPAIGN`：仅获取搜索广告推广系列。</li><li>`OTHER`：仅获取非 Smart+ 且非搜索广告类型的推广系列。</li></ul><br>若您不填写该字段，则将获取所有推广系列。<br><br><p><span style="color:darkred"><b>注意</b></span>: 本筛选条件仅支持在同步基础报表中使用。|
|create_time| BETWEEN | 推广系列、广告组、广告 | 传入的ID维度（`campaign_id`/`adgroup_id`/`ad_id`）的创建时间范围。使用此筛选条件时，筛选的值需要是合法的、包含两个元素的 JSON数组字符串，第一个元素为开始时间，第二个元素为结束时间。举例：`"[\"2022-02-24 11:57:51\",\"2022-03-24 11:57:51\"]"`。本筛选条件只能用于同步报表中。<br>建议：为了让任务成功执行及任务速度不受影响，创建时间的范围建议在6个月以内。|
|create_time| GREATER_THAN | 推广系列、广告组、广告| 传入的ID维度（`campaign_id`/`adgroup_id`/`ad_id`）的最早创建时间。格式：`YYYY-MM-DD HH:MM:SS`（UTC时区）。举例：`"2022-02-24 11:57:51"` 将返回晚于该时间创建的维度。本筛选条件只能用于同步报表中。<br>建议：为了让任务成功执行及任务速度不受影响，创建时间的范围建议在6个月以内。|
|create_time| LOWER_THAN |推广系列、广告组、广告 | 传入的ID维度（`campaign_id`/`adgroup_id`/`ad_id`）的最晚创建时间。格式：`YYYY-MM-DD HH:MM:SS`（UTC时区）。举例：`"2022-02-24 11:57:51"` 将返回早于该时间创建的维度。本筛选条件只能用于同步报表中。<br>建议：为了让任务成功执行及任务速度不受影响，创建时间的范围建议在6个月以内。|
← 基础报表中维度所支持指标支持的指标 →

内容来源：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 每日平台更新简报 →