报表

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

报表

可用命令：

cloudx report dashboard 用于汇总以及每日或每小时指标
cloudx report breakdown 用于按时间、库存与设备维度做 CloudX-only 自定义拆分
cloudx report bidders 用于竞价方表现
cloudx report apps 用于应用表现
cloudx report 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`	✅	✅	✅	✅	✅	✅
`--granularity`	✅	✅	❌	❌	❌	✅
`--test-mode`	✅	✅	✅	✅	✅	❌
`--app`	❌	❌	❌	❌	✅	❌
`--ad-unit-type`	❌	❌	❌	❌	✅	❌
`--country`	✅	✅	✅	✅	✅	✅
`--device-os`	✅	✅	✅	✅	✅	✅
`--source`	✅	❌	❌	✅	✅	❌
`--json`	✅	✅	✅	✅	✅	✅

时间段值

时间段解析基于 UTC。

省略 --period 时，所有报表命令都使用 today。

值	含义
`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 广告类型/格式。

指标

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

指标	含义
`requests`	CloudX 请求数。
`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

使用指标阈值过滤 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 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