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。

通用标志

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

各命令支持的标志

时间段值

常规报表的时间段默认基于 UTC。从 CLI 0.41 起，可在支持的命令中使用 --timezone 选择其他时区。省略 --period 时，这些命令使用 today。

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

校验规则：

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

报表时区

从 CLI 0.41 起，report dashboard、report apps、report ad-units、report bidders 和 report breakdown 支持 --timezone。使用 America/New_York 或 Asia/Shanghai 等 IANA 名称。省略此标志时，UTC 时间段、分桶和输出保持不变。这是报表命令标志，不是全局根标志。

cloudx report dashboard --period 2026-03-08 --timezone America/New_York

此示例选择从 2026-03-08T05:00:00Z 到 2026-03-09T03:59:59Z 的 23 小时本地日期。夏令时切换时，本地日期可能有 23 或 25 小时。last_7d 和 last_30d 仍选择滚动 168 小时和 720 小时窗口。

CLI 只将日历边界转换为 Unix 时间戳一次。直接调用 API 时，timezone 控制日历分桶；start_time 和 end_time 始终是绝对 Unix 时间戳，不会再次偏移。控制台的 date 以及日、周、月拆分标签使用所选时区。控制台的 bucket_start 和小时拆分键仍使用 UTC RFC 3339 时间戳，从而区分重复出现的本地小时。

SDK 报表、按小时分桶的控制台及拆分报表、以及按竞价方拆分的报表，均要求整个请求时间段内的时区偏移均为整小时。对这些报表使用 Asia/Kolkata 等非整小时偏移时区会返回错误。report ab-test 接受 --timezone UTC，拒绝非 UTC 时区。无效的时区名称也会返回错误。

现有范围限制仍然适用：起始时刻不得早于 2020-01-01T00:00:00Z，聚合报表窗口不得超过 744 小时。跨越秋季夏令时切换的 31 个日期可能超出该限制。

report export、活动导出和竞价检查仍使用 UTC，且不接受此标志。需求对比保留独立的已结束报表时间范围规则。

粒度值

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

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

report export 始终使用 UTC 分桶。

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

来源值

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

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

来源名称不区分大小写，CLI 会进行规范化。外部来源值表示转发该 ILRD 的聚合平台，而不是下游需求方网络，也不是 CloudX 的竞价方。例如 AppLovin MAX 中带有 ADMOB_BIDDING 需求的行会归入 applovin，而不是 admob。

admob 表示发布商应用转发的 AdMob Mediation ILRD，并不是 CloudX 的 AdMob estimated 需求；因此在 CloudX 控制台暂停 AdMob estimated 之后，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 可按小时显示图表行（未指定 --timezone 时使用 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 传入逗号分隔的列表。

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

指标

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

比率指标会基于每一行的汇总组件计算，不会对预先计算的比率做平均。 使用 --json 时，响应包含 dimensions、metrics、rows 和 row_count。每行有字符串 dimensions map 和数字 metrics map。两个 map 只包含请求的名称。CloudX 最多返回 100,000 行。

选项

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。从 CLI 0.41 起，在可用历史数据范围内，可请求任意长度的已结束日历日期窗口。CLI 0.40 及更早版本的显式时间范围最多为 31 个日历日期，包含起止日期。部分选定日期可能没有 CloudX 或需求方数据。

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

• 起始日期不得早于 2020-01-01。
• 结束日期不得早于起始日期。
• 结束日期必须符合 UTC 12:00 截止规则。

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

标志

需求方来源与 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 时包含所有受支持来源。

需求方业务 ID、需求方资产 ID 和 CloudX 广告单元 ID 都是实时标识，不是固定枚举。汇总和广告单元结果会汇总完整请求日期窗口。它们不提供 day、country、platform、mediator 或原始需求方报表行。不可用的需求方指标会从 JSON 中省略，不会以零返回。

人类可读的汇总表包含：

• 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 列表。

响应使用以下分页字段：

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

示例

每日导出按以下顺序返回 14 列：

date,network_name,app_name,app_store_id,platform,ad_unit_id,ad_type,network_placement,country,impressions,clicks,revenue,attempts,responses
2026-03-29,meta,Sample Puzzle,com.example.puzzle,iOS,ad-unit-home,banner,home-banner,US,1200,18,14.25,1500,960

date 是 UTC 日历日期。country 是 ISO alpha-2。app_store_id 是配置的应用 bundle，不总是数字商店 ID。network_name、应用 ID、广告单元 ID 和 placement ID 是动态值。该命令只返回生产数据。device_os 只接受 iOS 或 Android 作为过滤器，不会规范化返回的 platform 文本。

旧报表使用 SSP 请求作为 attempts，并为 responses 返回 0。SDK 报表使用广告请求作为 attempts，使用填充数作为 responses。

每小时导出只将首列替换为 bucket_start，它是 RFC 3339 UTC 时间戳：

bucket_start,network_name,app_name,app_store_id,platform,ad_unit_id,ad_type,network_placement,country,impressions,clicks,revenue,attempts,responses
2026-03-29T13:00:00Z,meta,Sample Puzzle,com.example.puzzle,iOS,ad-unit-home,banner,home-banner,US,120,2,1.43,150,96

JSON 输出

使用 --json 时，rows 是字符串数组的数组。每个行位置与 columns 对应；row_count 是返回行数。

相关链接

• CloudX CLI 概览
• 安装
• 身份认证命令
• 活动导出
• 示例