> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 报表

> 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 导出
* `cloudx report impressions export` 用于异步导出展示级收入数据

## 请求超时

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

```bash theme={null}
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`。

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

## 输出格式

### 人类可读格式

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

元信息块示例：

```text theme={null}
Period:      last_30d
Test mode:   production
Country:     US
Device OS:   iOS
Granularity: hourly
```

### JSON

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

```bash theme={null}
cloudx report dashboard --json
```

所有命令示例汇总在 [示例](/zh/cli/examples) 页面。

## `cloudx report dashboard`

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

### 用法

```bash theme={null}
cloudx report dashboard [--period <value>] [--granularity daily|hourly] [flags]
```

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

```bash theme={null}
cloudx report dashboard --period last_7d --source all
```

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

```bash theme={null}
cloudx report dashboard --period 2026-04-01 --granularity hourly
```

### 示例

```bash theme={null}
$ 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 时，请使用已支持来源过滤的控制台、应用和广告单元命令。

### 用法

```bash theme={null}
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` 会在分组后过滤行。它支持一个简单的指标比较：

```text theme={null}
<metric> <operator> <number>
```

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

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

有效示例：

```bash theme={null}
--having 'revenue > 10'
--having 'impressions >= 1000'
--having 'ctr < 1.5'
```

无效示例：

```bash theme={null}
--having 'revenue > 10 OR 1=1'
--having 'country = US'
--having 'revenue > impressions'
```

### 示例

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

```bash theme={null}
cloudx report breakdown --period last_7d --by day,country --metrics revenue,impressions,ecpm
```

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

```bash theme={null}
cloudx report breakdown --period 2026-04-01 --granularity hourly --by hour,app --metrics requests,impressions,fill_rate
```

按收入查看 Top 广告单元：

```bash theme={null}
cloudx report breakdown --by app,ad_unit --metrics revenue,ecpm --top 10
```

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

```bash theme={null}
cloudx report breakdown --by country --metrics revenue,impressions --having 'revenue > 10' --json
```

### 输出示例

```bash theme={null}
$ 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`

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

### 用法

```bash theme={null}
cloudx report bidders [--period <value>] [flags]
```

### 示例

```bash theme={null}
$ 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`

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

### 用法

```bash theme={null}
cloudx report apps [--period <value>] [flags]
```

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

```bash theme={null}
cloudx report apps --period last_30d --source cloudx,applovin
```

### 示例

```bash theme={null}
$ 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`

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

### 用法

```bash theme={null}
cloudx report ad-units [--period <value>] [flags]
```

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

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

```bash theme={null}
cloudx report ad-units --app com.example.game --source all
```

### 示例

```bash theme={null}
$ 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 格式导出报表数据。

### 用法

```bash theme={null}
cloudx report export [--period <value>] [--granularity daily|hourly] [flags]
```

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

```bash theme={null}
cloudx report export --period 2026-04-01 --granularity hourly
```

### 示例

```bash theme={null}
$ cloudx report export
date,network_name,country
2026-03-29,meta,US
```

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

```bash theme={null}
$ 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 请求的时限内完成。

### 用法

```bash theme={null}
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。生成文件最长保留七天。

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

### 示例

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

```bash theme={null}
cloudx report impressions export --date 2026-07-16
```

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

```bash theme={null}
cloudx report impressions export \
  --date 2026-07-16 \
  --output ./impressions-2026-07-16.csv.gz
```

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

```bash theme={null}
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
```

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

```bash theme={null}
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 测试版本（如适用）。              |

## 相关链接

* [CloudX CLI 概览](/zh/cli)
* [安装](/zh/cli/installation)
* [身份认证命令](/zh/cli/authentication)
* [示例](/zh/cli/examples)