报表

cloudx report 命令的公开参考，包括过滤器、支持的标志与输出格式。

报表

可用命令：

cloudx report dashboard 用于汇总以及每日或每小时指标
cloudx report breakdown 用于按时间、库存与设备维度做 CloudX-only 自定义拆分
cloudx report bidders 用于竞价方表现
cloudx report apps 用于应用表现
cloudx report ad-units 用于广告单元表现
cloudx report demand-comparison 用于对比 CloudX 与需求方汇总指标
cloudx report demand-comparison-ad-units 用于查看已映射或未映射的需求方广告单元
cloudx report export 用于 CSV 或 JSON 导出

请求超时

报表请求默认使用 60 秒 API 超时。若工作流需要更早失败，或较重报表需要更多时间，可以在命令之前使用全局 --timeout 标志。

cloudx --timeout 90s report export --period 2026-04-01..2026-04-07

--timeout 接受时长值，例如 30s、90s 或 2m。取值必须大于 0s，且不能超过 2m。

通用标志

大多数报表命令使用下列标志。需求对比使用独立的精简标志，因为它对比的是已结束的需求方日报，而不是实时投放数据。

标志	必填	说明
`--period`	否	时间范围，默认为 `today`。支持 `today`、`yesterday`、`last_7d`、`last_30d`、`YYYY-MM-DD`，或 `YYYY-MM-DD..YYYY-MM-DD`。
`--granularity`	否	报表分桶粒度。`report dashboard`、`report breakdown` 与 `report export` 支持。允许的值：`daily`、`hourly`。默认值：`daily`。
`--test-mode`	否	测试流量过滤。允许的值：`production`、`test`、`all`。默认值：`production`。
`--app`	否	应用 bundle 过滤。`report ad-units` 支持。
`--ad-unit-type`	否	广告单元类型过滤。仅 `report ad-units` 支持。允许的值：`BANNER`、`INTERSTITIAL`、`REWARDED`、`MREC`、`NATIVE`。
`--country`	否	ISO-2 国家代码，例如 `US` 或 `GB`。
`--device-os`	否	设备平台过滤。允许的值：`iOS`、`Android`。
`--source`	否	报表来源过滤。`report dashboard`、`report apps` 与 `report ad-units` 支持。省略时默认为 CloudX。
`--json`	否	输出结构化 JSON 而非人类可读格式。

各命令支持的标志

标志	控制台	拆分	竞价方	应用	广告单元	需求对比	需求对比广告单元	导出
`--period`	✅	✅	✅	✅	✅	✅	✅	✅
`--timezone`	❌	❌	❌	❌	❌	✅	✅	❌
`--granularity`	✅	✅	❌	❌	❌	❌	❌	✅
`--test-mode`	✅	✅	✅	✅	✅	❌	❌	❌
`--app`	❌	❌	❌	❌	✅	❌	❌	❌
`--ad-unit-type`	❌	❌	❌	❌	✅	❌	❌	❌
`--country`	✅	✅	✅	✅	✅	❌	❌	✅
`--device-os`	✅	✅	✅	✅	✅	❌	❌	✅
`--source`	✅	❌	❌	✅	✅	❌	❌	❌
`--demand-source`	❌	❌	❌	❌	❌	✅	✅	❌
`--provider-business-id`	❌	❌	❌	❌	❌	✅	✅	❌
`--provider-property-id`	❌	❌	❌	❌	❌	✅	✅	❌
`--cloudx-ad-unit-id`	❌	❌	❌	❌	❌	✅	✅	❌
`--view`	❌	❌	❌	❌	❌	❌	✅	❌
`--limit`	❌	❌	❌	❌	❌	❌	✅	❌
`--json`	✅	✅	✅	✅	✅	✅	✅	✅

时间段值

常规报表的时间段基于 UTC。省略 --period 时，这些命令使用 today。

需求对比按 --timezone 使用已结束的日历日期。其默认值和校验规则见下文。

值	含义
`today`	当前 UTC 当日
`yesterday`	前一个 UTC 当日
`last_7d`	当前 UTC 当日加上前 6 天
`last_30d`	当前 UTC 当日加上前 29 天
`2026-04-01`	单个 UTC 日期
`2026-04-01..2026-04-07`	含端点的 UTC 日期范围

校验规则：

结束日期不得早于起始日期。
--country 必须为规范化后的两位大写 ISO-2 国家代码。
--device-os 必须严格为 iOS 或 Android。
--test-mode 必须为 production、test 或 all。
--granularity 必须为 daily 或 hourly。

粒度值

当需要改变所选时间段内的报表分桶方式时，可以使用 --granularity。

值	含义
`daily`	UTC 日历日分桶。这是默认值。
`hourly`	UTC 小时分桶。`report dashboard`、`report breakdown` 与 `report export` 支持。

对于每小时控制台报表，人类可读的图表表格会使用 BUCKET START 而不是 DATE，JSON 图表行会包含 bucket_start 时间戳，例如 2026-04-01T13:00:00Z。

对于每小时导出，CSV 或 JSON 的首列会从 date 变为 bucket_start。

来源值

省略 --source 时，报表命令继续使用现有的 CloudX-only 报表路径。这会让控制台、应用与广告单元结果只统计 CloudX 服务的展示。

当需要在报表中包含 publisher SDK 转发的其他聚合平台展示级收入数据（ILRD）时，可以使用 --source。

值	含义
`cloudx`	仅 CloudX 服务的展示。
`<mediator>`	来自外部 ILRD 的聚合平台/平台来源，例如 `applovin`。
`cloudx,applovin`	用逗号分隔的指定来源对比。
`all`	CloudX 加上所有可用的外部聚合平台来源。

来源名称不区分大小写，CLI 会进行规范化。外部来源值来自 ILRD 的聚合平台/平台字段，而不是下游需求方网络。例如 AppLovin MAX 中带有 ADMOB_BIDDING 需求的行会归入 applovin，而不是 admob。

输出格式

人类可读格式

大多数命令会先输出一段元信息块，再输出表格。

元信息块示例：

Period:      last_30d
Test mode:   production
Country:     US
Device OS:   iOS
Granularity: hourly

JSON

传入 --json 以返回结构化 JSON：

cloudx report dashboard --json

所有命令示例汇总在示例页面。

`cloudx report dashboard`

显示汇总指标以及每日或每小时图表行。

用法

cloudx report dashboard [--period <value>] [--granularity daily|hourly] [flags]

使用 --source all 可在控制台收入、展示、eCPM 与来源拆分中包含外部聚合平台 ILRD：

cloudx report dashboard --period last_7d --source all

使用 --granularity hourly 可按 UTC 小时显示图表行：

cloudx report dashboard --period 2026-04-01 --granularity hourly

示例

$ cloudx report dashboard
Period:      today
Test mode:   production

Requests:     1.5M
Impressions:  1.2M
Revenue:      $14.9K
Fill Rate:    78.0%
eCPM:         $12.7
Clicks:       35.1K
CTR:          3.0%
Users:        42K

DATE        REQUESTS  IMPRESSIONS  REVENUE  CLICKS
2026-03-29  210K      163.8K       $2.1K    4.9K

`cloudx report breakdown`

按自选维度显示 CloudX-only 聚合指标。

此命令适合临时分析，例如按国家查看收入、按小时和应用查看填充率，或按广告单元查看 eCPM。它不接受 --source，也不包含外部聚合平台 ILRD 或提供方收入。需要外部 ILRD 时，请使用已支持来源过滤的控制台、应用和广告单元命令。

用法

cloudx report breakdown --by <dimensions> --metrics <metrics> [flags]

维度

使用 --by 传入逗号分隔的列表。

维度	含义
`hour`	UTC 小时桶。需要 `--granularity hourly`。
`day`	UTC 日历日。
`week`	从周日开始的 UTC 周桶。
`month`	UTC 月桶。
`country`	设备国家。
`os`	设备操作系统。
`app`	CloudX 报表中的应用 bundle 或应用标识。
`ad_unit`	CloudX 广告单元 ID。
`format`	CloudX 广告类型/格式。
`bidder`	CloudX 竞价方 ID。

每次最多可以请求四个维度。bidder 维度适用于 2026 年 6 月 1 日或之后开始的报表时间段。

指标

使用 --metrics 传入逗号分隔的列表。

指标	含义
`requests`	广告请求数。按竞价方拆分时，同一维度组中的每个竞价方都会重复显示此值。
`bid_requests`	发送给竞价方的竞价请求数。需要使用 `bidder` 维度。
`fills`	填充的广告请求数。按竞价方拆分时，表示该竞价方的胜出次数。
`impressions`	CloudX 展示数。
`revenue`	CloudX 收入。
`fill_rate`	`(impressions / requests) * 100`——0-100 的百分比，而非比值。
`ecpm`	`revenue * 1000 / impressions`。
`clicks`	点击数。
`ctr`	`(clicks / impressions) * 100`——0-100 的百分比，而非比值。

比率指标会基于每一行的汇总组件计算，不会对预先计算的比率做平均。

选项

标志	说明
`--granularity daily`	默认值。用于 `day`、`week` 或 `month` 等按日兼容的时间维度。
`--granularity hourly`	启用 UTC 小时桶与 `hour` 维度。
`--top N`	按第一个请求的指标排序，返回前 `N` 行。
`--bottom N`	按第一个请求的指标排序，返回后 `N` 行。
`--having <expr>`	按指标表达式过滤行，例如 `revenue > 10`。

Having 表达式

--having 会在分组后过滤行。它支持一个简单的指标比较：

<metric> <operator> <number>

支持的操作符：<、<=、=、==、!=、>=、>。

指标必须是上方列出的受支持拆分指标之一，右侧必须是数字。== 会作为 = 的别名处理。不支持布尔逻辑、字符串、SQL 函数和字段间比较。

有效示例：

--having 'revenue > 10'
--having 'impressions >= 1000'
--having 'ctr < 1.5'

无效示例：

--having 'revenue > 10 OR 1=1'
--having 'country = US'
--having 'revenue > impressions'

示例

按日期和国家查看收入、展示与 eCPM：

cloudx report breakdown --period last_7d --by day,country --metrics revenue,impressions,ecpm

查看单日按小时和应用拆分的填充率：

cloudx report breakdown --period 2026-04-01 --granularity hourly --by hour,app --metrics requests,impressions,fill_rate

按收入查看 Top 广告单元：

cloudx report breakdown --by app,ad_unit --metrics revenue,ecpm --top 10

按应用、格式和广告单元查看竞价方的投放与点击表现：

cloudx report breakdown --by bidder,app,format,ad_unit --metrics requests,bid_requests,fills,impressions,clicks,ctr

使用指标阈值过滤 JSON 输出：

cloudx report breakdown --by country --metrics revenue,impressions --having 'revenue > 10' --json

输出示例

$ cloudx report breakdown --period 2026-04-01 --granularity hourly --by hour,country --metrics revenue,impressions,ecpm
Period:       2026-04-01
Test mode:    production
Granularity:  hourly

HOUR                  COUNTRY  REVENUE  IMPRESSIONS  ECPM
2026-04-01T00:00:00Z  US       $128.4   10.2K        $12.6
2026-04-01T01:00:00Z  GB       $84.1    6.8K         $12.4

`cloudx report bidders`

显示所选时间段内的竞价方级别表现。

用法

cloudx report bidders [--period <value>] [flags]

示例

$ cloudx report bidders
Period:      today
Test mode:   production

BIDDER  REQUESTS  BIDS  BID RATE  IMPRESSIONS  WIN RATE  REVENUE  ECPM
meta    850K      629K  74.0%     314.5K       50.0%     $5.6K    $17.7

`cloudx report apps`

显示所选时间段内的应用级表现。

用法

cloudx report apps [--period <value>] [flags]

使用逗号分隔的来源列表，可以按应用对比 CloudX 与某个聚合平台：

cloudx report apps --period last_30d --source cloudx,applovin

示例

$ cloudx report apps
Period:      today
Test mode:   production

APP ID            NAME          PLATFORM  IMPRESSIONS  FILL RATE  REVENUE  ECPM
com.example.game  Example Game  iOS       1.8M         78.0%      $8.4K    $4.7

`cloudx report ad-units`

显示所选时间段内的广告单元级表现。

用法

cloudx report ad-units [--period <value>] [flags]

这是当前唯一同时支持 --app 与 --ad-unit-type 的报表命令。

配合 --app 使用 --source all，可查看同一应用广告单元上的 CloudX 与外部聚合平台收入：

cloudx report ad-units --app com.example.game --source all

示例

$ cloudx report ad-units
Period:      today
Test mode:   production

AD UNIT ID  NAME                APP NAME      APP BUNDLE        TYPE    IMPRESSIONS  FILL RATE  REVENUE  ECPM
abc123      Home Screen Banner  Example Game  com.example.game  BANNER  450K         55.0%      $2.1K    $4.7

`cloudx report demand-comparison`

对比 CloudX 确认的收入、eCPM 和展示数与受支持需求方的每日报表。

该命令需要 reports:read 权限和需求对比功能访问权限。账号无权使用该功能时，API 返回 403 Forbidden。

用法

cloudx report demand-comparison [flags]

已结束的报表时间范围

省略 --period 时，命令选择最近 30 个已结束的日历日期：

UTC 时间 12:00 或之后，时间范围结束于昨天。
UTC 时间 12:00 之前，时间范围结束于前天。

显式时间段接受 YYYY-MM-DD 或 YYYY-MM-DD..YYYY-MM-DD。CLI 按 --timezone 指定的 IANA 时区转换这些日历日期。默认时区为 UTC。

时间范围必须满足以下规则：

起始日期不得早于 2020-01-01。
结束日期不得早于起始日期。
时间范围最多包含 31 个日历日期。
结束日期必须符合 UTC 12:00 截止规则。

需求对比命令不接受 today、yesterday、last_30d 等命名时间段。

标志

标志	汇总	广告单元	说明
`--period`	可选	可选	单个日期或含端点的日期范围。省略时选择最近 30 个已结束日期。
`--timezone`	可选	可选	用于转换日历日期的 IANA 时区。默认值：`UTC`。
`--demand-source`	可选	必填	`digitalturbine`、`inmobi`、`liftoff`、`meta` 或 `moloco`。汇总命令接受零至五个值。广告单元命令只接受一个值。
`--provider-business-id`	可选	可选	需求方业务 ID 过滤器。
`--provider-property-id`	可选	可选	需求方资产 ID 过滤器。
`--cloudx-ad-unit-id`	可选	可选	关联的 CloudX 广告单元 ID 过滤器。
`--view`	不支持	可选	`mapped` 或 `unmapped`。默认值：`mapped`。
`--limit`	不支持	可选	广告单元最大行数。范围：`1` 至 `1000`。默认值：`1000`。
`--json`	可选	可选	输出完整 API 响应，而不是人类可读表格。

需求方来源与 ID 过滤器可重复传入，也可使用逗号组合多个值：

cloudx report demand-comparison \
  --demand-source meta,moloco \
  --provider-business-id business-1 \
  --provider-business-id business-2,business-3

CLI 会去除值两端的空格并保留 ID 大小写。空值或重复值会导致错误。汇总命令省略 --demand-source 时包含所有受支持来源。

人类可读的汇总表包含：

CloudX、需求方和差值的收入、eCPM 与展示数
已匹配广告单元数和 CloudX 广告单元总数
has_mapping_gaps，在表格中显示为 MAPPING GAPS
最新需求方报表日期和需求方报表日期数量

has_mapping_gaps 包含任一侧缺失或不明确的映射。仅存在于 CloudX 一侧的映射缺口会保留在汇总警告中，不会成为广告单元报表中的需求方行。

cloudx report demand-comparison --demand-source meta,moloco

`cloudx report demand-comparison-ad-units`

返回单个需求方来源的需求方广告单元聚合结果。

用法

cloudx report demand-comparison-ad-units --demand-source DEMAND_SOURCE [flags]

默认的 --view mapped 输出包含需求方标识、关联的 CloudX 广告单元 ID，以及 CloudX 与需求方的收入、eCPM 和展示数对比指标。

使用 --view unmapped 可返回当前没有 CloudX 映射或归因不明确的需求方行：

cloudx report demand-comparison-ad-units \
  --demand-source moloco \
  --view unmapped

未映射行的状态为 status: unmapped。excluded_partner_revenue 和 excluded_partner_impressions 表示未计入已映射对比的需求方收入与展示数。该视图的人类可读表格不会显示值为零的 CloudX 对比列。

API 会先形成每个需求方广告单元的聚合结果，再应用 --cloudx-ad-unit-id。任一关联的 CloudX ID 匹配时，响应保留该聚合结果的完整总计和完整 cloudx_ad_unit_ids 列表。

响应使用以下分页字段：

字段	含义
`row_count`	返回的行数，不超过 `limit`。
`limit`	请求的最大行数。
`truncated`	匹配行数多于响应所含行数时为 `true`。

truncated 为 true 时，人类可读输出会显示警告。使用更具体的需求方或广告单元过滤器可缩小结果范围。

`cloudx report export`

默认以 CSV 格式导出报表数据。

用法

cloudx report export [--period <value>] [--granularity daily|hourly] [flags]

当下游报表需要 UTC 小时分桶时，使用 --granularity hourly：

cloudx report export --period 2026-04-01 --granularity hourly

示例

$ cloudx report export
date,network_name,country
2026-03-29,meta,US

每小时导出会使用 bucket_start 作为首列：

$ cloudx report export --period 2026-03-29 --granularity hourly
bucket_start,network_name,country
2026-03-29T13:00:00Z,meta,US

JSON 输出

使用 --json 时，响应中包含：

columns
rows
row_count