报表

可用命令：

cloudx report dashboard 用于汇总以及每日或每小时指标
cloudx report breakdown 用于按时间、库存与设备维度做 CloudX-only 自定义拆分
cloudx report bidders 用于竞价方表现
cloudx report apps 用于应用表现
cloudx report ad-units 用于广告单元表现
cloudx report export 用于 CSV 或 JSON 导出
cloudx report impressions export 用于异步导出展示级收入数据

请求超时

报表请求默认使用 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` 和 `report impressions export` 支持。
`--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。

当 --source 包含外部聚合平台时，填充率仍然只代表 CloudX，因为外部 ILRD 包含展示与收入，但不包含 CloudX 请求数。CLI 会将其标注为 Fill Rate (CloudX-only)。

输出格式

人类可读格式

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

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`。
`ecpm`	`revenue * 1000 / impressions`。
`clicks`	点击数。
`ctr`	`clicks / impressions`。

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

选项

标志	说明
`--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

`cloudx report impressions export`

将完整一天的展示级收入数据异步导出为 gzip 压缩的 CSV 文件。导出任务在后台运行，因此大型结果集无需在普通 API 请求的时限内完成。

用法

cloudx report impressions export --date YYYY-MM-DD [过滤条件] [--wait] [--output <路径>]

--date 为必填项，必须是过去 45 天内已经结束的 UTC 日期。当前 UTC 日期尚未结束，因此不能导出。

选项

标志	必填	说明
`--date`	是	`YYYY-MM-DD` 格式的已结束 UTC 日期，必须在过去 45 天内。
`--app-id`	否	CloudX 应用 ID。不能与 `--app` 同时使用。
`--app`	否	应用包名，例如 `com.example.game`。不能与 `--app-id` 同时使用。
`--ad-unit-id`	否	CloudX 广告单元 ID。
`--country`	否	ISO 3166-1 alpha-2 国家代码，例如 `US` 或 `GB`。
`--device-os`	否	设备操作系统。可选值：`iOS`、`Android`。
`--bidder`	否	竞价方/广告网络代码。
`--line-item-id`	否	CloudX 订单项 ID。
`--test-mode`	否	要包含的流量：`production`、`test` 或 `all`。默认值：`production`。
`--wait`	否	轮询直至导出就绪或失败。最长可等待 2 小时 15 分钟。
`--output`	否	将就绪的 `.csv.gz` 文件下载到此路径。隐含启用 `--wait`。

每个账户同时最多只能处理两个展示导出任务。使用相同日期与过滤条件再次提交时，CLI 会复用匹配的排队中、运行中或已完成导出，而不会创建重复任务。导出就绪后，CloudX 会返回一个有效期为一小时的下载 URL。在生成文件仍处于保留期内时，重新运行相同命令可获取新的 URL。生成文件最长保留七天。

展示导出可能包含广告标识符、库存元数据和原始收入数据。请安全存储下载文件，仅允许授权用户访问，并在不再需要时删除文件。

示例

提交导出任务，并打印导出 ID 与当前状态：

cloudx report impressions export --date 2026-07-16

等待任务完成并下载结果：

cloudx report impressions export \
  --date 2026-07-16 \
  --output ./impressions-2026-07-16.csv.gz

导出美国地区某个 iOS 应用的生产流量展示：

cloudx report impressions export \
  --date 2026-07-16 \
  --app com.example.game \
  --country US \
  --device-os iOS \
  --test-mode production \
  --output ./example-game-us-ios.csv.gz

检查下载的压缩文件并预览表头与前几行：

gzip -t ./impressions-2026-07-16.csv.gz
gzip -cd ./impressions-2026-07-16.csv.gz | head

CSV 字段

CSV 中每一行对应一条匹配的展示记录。不保证行顺序。

字段	说明
`event_time`	UTC 展示事件时间。
`impression_id`	唯一展示事件 ID。
`auction_id`	关联的竞价 ID。
`bid_id`	获胜出价 ID。
`app_id`	CloudX 应用 ID。
`app_bundle`	应用包名。
`ad_unit_id`	CloudX 广告单元 ID。
`ad_unit_name`	广告单元显示名称。
`ad_format`	该展示记录的广告格式。
`placement`	发布商广告位值。
`custom_data`	发布商提供的自定义数据。
`country`	大写 ISO 国家代码。
`device_os`	设备操作系统。
`device_type`	该展示记录的设备类型。
`advertising_id`	设备广告标识符（如有）。
`advertising_vendor_id`	供应商标识符（如有）。
`test_mode`	测试流量为 `true`；生产流量为 `false`。
`network`	竞价方/广告网络代码。
`line_item_id`	CloudX 订单项 ID。
`price_cpm`	以 CPM 表示的获胜价格。
`revenue_usd`	此次单次展示产生的美元收入。
`currency`	收入币种。当前为 `USD`。
`revenue_precision`	收入精度。当前为 `exact`。
`creative_id`	创意 ID（如有）。
`network_placement_id`	广告网络侧广告位 ID（如有）。
`ab_test_id`	A/B 测试 ID（如适用）。
`ab_test_variant`	A/B 测试版本（如适用）。

​报表

​请求超时

​通用标志

​各命令支持的标志

​时间段值

​粒度值

​来源值

​输出格式

​人类可读格式

​JSON

​cloudx report dashboard

​用法

​示例

​cloudx report breakdown

​用法

​维度

​指标

​选项

​Having 表达式

​示例

​输出示例

​cloudx report bidders

​用法

​示例

​cloudx report apps

​用法

​示例

​cloudx report ad-units

​用法

​示例

​cloudx report export

​用法

​示例

​JSON 输出

​cloudx report impressions export

​用法

​选项

​示例

​CSV 字段

​相关链接

报表

请求超时

通用标志

各命令支持的标志

时间段值

粒度值

来源值

输出格式

人类可读格式

JSON

`cloudx report dashboard`

用法

示例

`cloudx report breakdown`

用法

维度

指标

选项

Having 表达式

示例

输出示例

`cloudx report bidders`

用法

示例

`cloudx report apps`

用法

示例

`cloudx report ad-units`

用法

示例

`cloudx report export`

用法

示例

JSON 输出

`cloudx report impressions export`

用法

选项

示例

CSV 字段

相关链接