# reports/network 字段参考
> GET /reports/network 的参数、值和响应参考。
<!-- source: /zh/api-reference/reporting/reportsnetwork -->

## 维度列表

在 `dimensions`、`filter.<dimension>` 和 `is_null` 中使用以下名称。类型和值参见[维度](#维度)。

| 维度                              | 说明                              |
| ------------------------------- | ------------------------------- |
| `day`                           | 广告网络所在时区的报表日期。                  |
| `provider`                      | 广告网络。                           |
| `provider_account_id`           | 广告网络账号 ID。                      |
| `provider_account_secondary_id` | Moloco publisher ID。            |
| `account_name`                  | CloudX 账号名称。                    |
| `property_id`                   | Meta property ID。               |
| `app_id`                        | 广告网络的应用 ID。                     |
| `app_name`                      | 广告网络的应用名称。                      |
| `package`                       | Android 包名或 iOS bundle ID。      |
| `store_id`                      | 应用商店 ID。                        |
| `platform`                      | 规范化后的平台。                        |
| `country`                       | 国家/地区代码。                        |
| `format`                        | 规范化后的广告格式。                      |
| `placement_id`                  | 广告网络的广告位 ID。                    |
| `placement_reference_id`        | Liftoff placement reference ID。 |
| `placement_name`                | 广告网络的广告位名称。                     |
| `ad_size`                       | Liftoff 广告尺寸。                   |
| `incentivized`                  | Liftoff 激励流量标记。                 |
| `original_platform`             | 广告网络原样上报的平台。                    |
| `original_format`               | 广告网络原样上报的广告格式。                  |
| `source_timezone`               | 报表日期所用时区。始终包含。                  |
| `currency`                      | 收入币种。始终包含。                      |

## 广告网络报表参考

该端点返回广告网络发布的每日报表，数据由 CloudX 从 [Settings > Data sources](https://app.cloudx.io/settings/data-sources) 中的连接采集。支持的广告网络为 Digital Turbine、InMobi、Liftoff、Meta 和 Moloco。请求只读取已存储的报表，不会调用广告网络。

每个响应的每一行都包含展示数、点击数、收入、eCPM 和平均 CPC。使用 `dimensions` 选择拆分方式，使用 `filter.<dimension>` 匹配值，并使用 `limit`、`offset` 和 `snapshot` 分页读取结果。

API key 需要 `reports:read` 权限，且账号必须已启用广告网络报表。如需启用，请联系您的 CloudX 客户经理。没有访问权限时，端点返回 `403`。

### 参数

| 参数                   | 必填 | 默认值                                                              | 可接受的值                                              |
| -------------------- | -- | ---------------------------------------------------------------- | -------------------------------------------------- |
| `start_date`         | 是  | —                                                                | `YYYY-MM-DD`，例如 `2026-09-01`。                      |
| `end_date`           | 是  | —                                                                | `YYYY-MM-DD`，不得早于 `start_date`。范围最多 90 天，包含首尾两天。   |
| `dimensions`         | 否  | `day,provider,provider_account_id,provider_account_secondary_id` | 逗号分隔的[维度](#维度)列表，例如 `day,provider,app_id,country`。 |
| `filter.<dimension>` | 否  | —                                                                | 任一[维度](#维度)的精确值。重复同一过滤器可匹配多个值中的任意一个。               |
| `is_null`            | 否  | —                                                                | 维度名称。选择该维度未知的行。重复传入可指定多个维度。                        |
| `sort_by`            | 否  | 分组列                                                              | `revenue`。                                         |
| `sort_order`         | 否  | `desc`                                                           | `desc` 或 `asc`。需要同时传入 `sort_by`。                   |
| `limit`              | 否  | `1000`                                                           | `1` 至 `10000`。                                     |
| `offset`             | 否  | `0`                                                              | `0` 至 `1000000`。                                   |
| `snapshot`           | 否  | —                                                                | 第一页返回的 `page.snapshot`：64 个小写十六进制字符。               |
| `format`             | 否  | `json`                                                           | `json` 或 `csv`。                                    |

除 `filter.<dimension>` 和 `is_null` 外，每个参数只能出现一次，且不能为空。未知参数或维度、重复的参数，或这些参数的空值都会返回 `400`。`filter.<dimension>` 的空值有效，用于匹配空字符串。

### 维度

`dimensions` 接受下表中的名称，顺序不限。响应中的列始终按本表顺序排列。即使省略，`source_timezone` 和 `currency` 也始终参与分组。

| 维度                              | 类型               | 值                                                              |
| ------------------------------- | ---------------- | -------------------------------------------------------------- |
| `day`                           | string           | 报表日期，`YYYY-MM-DD`，按广告网络的 `source_timezone` 计算。                 |
| `provider`                      | string           | `digitalturbine`、`inmobi`、`liftoff`、`meta` 或 `moloco`。         |
| `provider_account_id`           | string           | 数据源连接中的广告网络账号。参见[广告网络账号](#广告网络账号)。                             |
| `provider_account_secondary_id` | string           | Moloco publisher ID。其他广告网络为空字符串。                               |
| `account_name`                  | string 或 `null`  | 您的 CloudX 账号名称。                                                |
| `property_id`                   | string 或 `null`  | Meta property ID。                                              |
| `app_id`                        | string 或 `null`  | 广告网络的应用 ID。                                                    |
| `app_name`                      | string 或 `null`  | 广告网络的应用名称。                                                     |
| `package`                       | string 或 `null`  | Android 包名或 iOS bundle ID，例如 `com.example.game`。               |
| `store_id`                      | string 或 `null`  | 应用商店 ID，例如数字形式的 App Store ID。                                  |
| `platform`                      | string 或 `null`  | `android`、`ios` 或 `fireos`。                                    |
| `country`                       | string 或 `null`  | 小写 ISO 3166-1 alpha-2 代码，例如 `us`。参见[国家/地区代码](#国家地区代码)。         |
| `format`                        | string 或 `null`  | `banner`、`interstitial`、`native` 或 `rewarded`。参见[广告格式](#广告格式)。 |
| `placement_id`                  | string 或 `null`  | 广告网络的广告位或广告单元 ID。                                              |
| `placement_reference_id`        | string 或 `null`  | Liftoff placement reference ID。                                |
| `placement_name`                | string 或 `null`  | 广告网络的广告位或广告单元名称。                                               |
| `ad_size`                       | string 或 `null`  | Liftoff 广告尺寸，例如 `320x50`。                                      |
| `incentivized`                  | boolean 或 `null` | Liftoff 激励流量标记：`true` 或 `false`。                               |
| `original_platform`             | string 或 `null`  | 广告网络原样上报的平台。                                                   |
| `original_format`               | string 或 `null`  | 广告网络原样上报的广告格式。                                                 |
| `source_timezone`               | string           | 定义广告网络报表日期的时区：Meta 为 `America/Los_Angeles`，其他广告网络为 `UTC`。      |
| `currency`                      | string 或 `null`  | 广告网络上报的收入币种，例如 `USD`。广告网络未上报币种时为 `null`。                       |

`null` 表示广告网络未上报该值，或上报的值无法被 CloudX 规范化。报表没有聚合平台维度。

#### 收入币种

CloudX 不会换算收入。行始终按 `currency` 拆分；币种未知的行还会保留 `provider`、`provider_account_id` 和 `provider_account_secondary_id`，即使您没有请求这些维度。这样，可能属于不同币种的收入永远不会被加总到同一行。

只要结果中有任一行币种未知，`fields` 就会包含这三列。币种已知的行在您未请求的这些列中返回 `null`。

Digital Turbine 上报 `USD`。Liftoff、InMobi、Meta 和 Moloco 目前返回 `currency: null`，因此它们的行会保留广告网络账号列。

#### 各广告网络提供的维度

广告网络未上报的维度返回 `null`。因此，针对该维度的 `filter.<dimension>` 会排除该广告网络的行；如需选择这些行，请使用 `is_null`。

| 维度                                       | Digital Turbine | InMobi | Liftoff | Meta | Moloco |
| ---------------------------------------- | --------------- | ------ | ------- | ---- | ------ |
| `account_name`                           | 是               | 是      | 是       | 是    | 是      |
| `property_id`                            | —               | —      | —       | 是    | —      |
| `app_id`                                 | 是               | 是      | 是       | —    | 是      |
| `app_name`                               | 是               | 是      | 是       | —    | 是      |
| `package`、`store_id`                     | 是               | 是      | 是       | —    | 是      |
| `platform`、`original_platform`、`country` | 是               | 是      | 是       | 是    | 是      |
| `format`、`original_format`               | 是               | 是      | 是       | —    | 是      |
| `placement_id`                           | 是               | 是      | 是       | 是    | 是      |
| `placement_reference_id`                 | —               | —      | 是       | —    | —      |
| `placement_name`                         | —               | 是      | 是       | 是    | 是      |
| `ad_size`、`incentivized`                 | —               | —      | 是       | —    | —      |
| `currency`                               | 是               | —      | —       | —    | —      |

`package` 保存包名形式的标识符，例如 `com.example.game`。`store_id` 保存应用商店标识符，例如数字形式的 App Store ID。Digital Turbine、InMobi 和 Liftoff 只上报一个应用标识符，CloudX 根据其格式填入两者之一。Moloco 两者都会上报。

#### 广告网络账号

| 广告网络            | `provider_account_id`        | `provider_account_secondary_id` |
| --------------- | ---------------------------- | ------------------------------- |
| Digital Turbine | Digital Turbine publisher ID | 空字符串                            |
| InMobi          | InMobi account ID            | 空字符串                            |
| Liftoff         | Liftoff customer ID          | 空字符串                            |
| Meta            | Meta business ID             | 空字符串                            |
| Moloco          | Moloco platform ID           | Moloco publisher ID             |

#### 广告格式

`format` 是规范化后的广告格式。`original_format` 保留广告网络自己的值。

| 广告网络            | `original_format`                            | `format`       |
| --------------- | -------------------------------------------- | -------------- |
| Digital Turbine | `banner`、`interstitial`、`native`             | 相同值            |
| Digital Turbine | `rewarded`、`rewarded_video`、`rewarded video` | `rewarded`     |
| InMobi          | `banner`、`interstitial`、`native`             | 相同值            |
| InMobi          | `rewarded`、`rewarded_video`、`rewarded video` | `rewarded`     |
| Liftoff         | `banner`、`native`                            | 相同值            |
| Liftoff         | `video` 且 `incentivized: true`               | `rewarded`     |
| Liftoff         | `video` 且 `incentivized: false`              | `interstitial` |
| Moloco          | `banner`、`interstitial`、`native`             | 相同值            |
| Moloco          | `reward_video`、`rewarded`                    | `rewarded`     |
| Meta            | 不上报                                          | `null`         |

匹配时忽略大小写和首尾空格。其他任何值都返回 `format: null`；如需选择这些行，请按 `original_format` 过滤。

#### 平台

`platform` 为 `android`、`ios` 或 `fireos`。广告网络上报的 `iphone` 和 `ipad` 规范化为 `ios`，`amazon` 和 `fire os` 规范化为 `fireos`。其他任何值返回 `platform: null`。`original_platform` 保留广告网络自己的值。

#### 国家/地区代码

`country` 是小写 ISO 3166-1 alpha-2 代码。CloudX 会规范化广告网络上报的 alpha-2 代码、alpha-3 代码和英文国家/地区名称。`xk` 表示科索沃。无法识别的值返回 `country: null`。

### 全部 250 个国家/地区代码

|   | 代码                                                                                                                 |
| - | ------------------------------------------------------------------------------------------------------------------ |
| A | `ad` `ae` `af` `ag` `ai` `al` `am` `ao` `aq` `ar` `as` `at` `au` `aw` `ax` `az`                                    |
| B | `ba` `bb` `bd` `be` `bf` `bg` `bh` `bi` `bj` `bl` `bm` `bn` `bo` `bq` `br` `bs` `bt` `bv` `bw` `by` `bz`           |
| C | `ca` `cc` `cd` `cf` `cg` `ch` `ci` `ck` `cl` `cm` `cn` `co` `cr` `cu` `cv` `cw` `cx` `cy` `cz`                     |
| D | `de` `dj` `dk` `dm` `do` `dz`                                                                                      |
| E | `ec` `ee` `eg` `eh` `er` `es` `et`                                                                                 |
| F | `fi` `fj` `fk` `fm` `fo` `fr`                                                                                      |
| G | `ga` `gb` `gd` `ge` `gf` `gg` `gh` `gi` `gl` `gm` `gn` `gp` `gq` `gr` `gs` `gt` `gu` `gw` `gy`                     |
| H | `hk` `hm` `hn` `hr` `ht` `hu`                                                                                      |
| I | `id` `ie` `il` `im` `in` `io` `iq` `ir` `is` `it`                                                                  |
| J | `je` `jm` `jo` `jp`                                                                                                |
| K | `ke` `kg` `kh` `ki` `km` `kn` `kp` `kr` `kw` `ky` `kz`                                                             |
| L | `la` `lb` `lc` `li` `lk` `lr` `ls` `lt` `lu` `lv` `ly`                                                             |
| M | `ma` `mc` `md` `me` `mf` `mg` `mh` `mk` `ml` `mm` `mn` `mo` `mp` `mq` `mr` `ms` `mt` `mu` `mv` `mw` `mx` `my` `mz` |
| N | `na` `nc` `ne` `nf` `ng` `ni` `nl` `no` `np` `nr` `nu` `nz`                                                        |
| O | `om`                                                                                                               |
| P | `pa` `pe` `pf` `pg` `ph` `pk` `pl` `pm` `pn` `pr` `ps` `pt` `pw` `py`                                              |
| Q | `qa`                                                                                                               |
| R | `re` `ro` `rs` `ru` `rw`                                                                                           |
| S | `sa` `sb` `sc` `sd` `se` `sg` `sh` `si` `sj` `sk` `sl` `sm` `sn` `so` `sr` `ss` `st` `sv` `sx` `sy` `sz`           |
| T | `tc` `td` `tf` `tg` `th` `tj` `tk` `tl` `tm` `tn` `to` `tr` `tt` `tv` `tw` `tz`                                    |
| U | `ua` `ug` `um` `us` `uy` `uz`                                                                                      |
| V | `va` `vc` `ve` `vg` `vi` `vn` `vu`                                                                                 |
| W | `wf` `ws`                                                                                                          |
| X | `xk`                                                                                                               |
| Y | `ye` `yt`                                                                                                          |
| Z | `za` `zm` `zw`                                                                                                     |

英国为 `gb`，不存在 `uk` 值。

### 过滤器

`filter.<dimension>` 精确匹配任一维度的值，区分大小写，无论该维度是否在 `dimensions` 中。

* 重复同一过滤器可匹配其中任意一个值：`filter.country=us&filter.country=ca`。
* 不同过滤器必须同时满足：`filter.platform=ios&filter.country=us`。
* 过滤值与响应中的文本一致：`filter.day=2026-09-01`、`filter.incentivized=true`，空字符串写作 `filter.provider_account_secondary_id=`。
* `is_null=<dimension>` 选择该维度为 `null` 的行。同一维度不能同时使用 `is_null` 和 `filter.<dimension>`。
* 每个过滤器最多接受 100 个值，每个值最多 1,024 字节。

逗号分隔的过滤值不会被拆分：`filter.country=us,ca` 不会匹配任何行。

### 指标

每一行最后是以下指标列。

| 指标                    | 类型              | 含义                                                 |
| --------------------- | --------------- | -------------------------------------------------- |
| `impressions`         | 十进制字符串或 `null`  | 广告网络上报的展示数。                                        |
| `clicks`              | 十进制字符串或 `null`  | 广告网络上报的点击数。                                        |
| `revenue`             | number 或 `null` | 广告网络上报的收入，币种为该行的币种。                                |
| `ecpm`                | number 或 `null` | `revenue * 1000 / impressions`。展示数为 `0` 时为 `null`。 |
| `average_cpc`         | number 或 `null` | `revenue / clicks`。点击数为 `0` 时为 `null`。             |
| `missing_impressions` | 十进制字符串          | 该分组中缺少展示数的广告网络报表行数。                                |
| `missing_clicks`      | 十进制字符串          | 该分组中缺少点击数的广告网络报表行数。                                |
| `missing_revenue`     | 十进制字符串          | 该分组中缺少收入的广告网络报表行数。                                 |

计数使用字符串，以便超过 253 的值保持完整精度。只要分组中任一广告网络报表行缺少某项指标，该指标即为 `null`；CloudX 不返回部分加总。只要任一输入指标为 `null`，`ecpm` 和 `average_cpc` 就为 `null`。广告网络上报的零是有效值，不算缺失。

### JSON 响应

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-01&dimensions=day,provider,country&filter.country=us" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

```json
{
  "query_time": "2026-09-02T09:30:00.123456Z",
  "fields": ["day", "provider", "provider_account_id", "provider_account_secondary_id", "country", "source_timezone", "currency", "impressions", "clicks", "revenue", "ecpm", "average_cpc", "missing_impressions", "missing_clicks", "missing_revenue"],
  "rows": [
    {"day": "2026-09-01", "provider": "digitalturbine", "provider_account_id": null, "provider_account_secondary_id": null, "country": "us", "source_timezone": "UTC", "currency": "USD", "impressions": "15320", "clicks": "201", "revenue": 68.94, "ecpm": 4.5, "average_cpc": 0.34298507462686567, "missing_impressions": "0", "missing_clicks": "0", "missing_revenue": "0"},
    {"day": "2026-09-01", "provider": "liftoff", "provider_account_id": "8f14e45fceea167a5a36dedd4bea2543", "provider_account_secondary_id": "", "country": "us", "source_timezone": "UTC", "currency": null, "impressions": "48210", "clicks": "612", "revenue": 241.05, "ecpm": 5, "average_cpc": 0.3938725490196079, "missing_impressions": "0", "missing_clicks": "0", "missing_revenue": "0"},
    {"day": "2026-09-01", "provider": "meta", "provider_account_id": "1029384756473829", "provider_account_secondary_id": "", "country": "us", "source_timezone": "America/Los_Angeles", "currency": null, "impressions": "30500", "clicks": "305", "revenue": 152.5, "ecpm": 5, "average_cpc": 0.5, "missing_impressions": "0", "missing_clicks": "0", "missing_revenue": "0"},
    {"day": "2026-09-01", "provider": "moloco", "provider_account_id": "EXAMPLE_PLATFORM", "provider_account_secondary_id": "EXAMPLE_PUBLISHER", "country": "us", "source_timezone": "UTC", "currency": null, "impressions": "9140", "clicks": "88", "revenue": 41.13, "ecpm": 4.5, "average_cpc": 0.46738636363636366, "missing_impressions": "0", "missing_clicks": "0", "missing_revenue": "0"}
  ],
  "coverage": [
    {"provider": "digitalturbine", "provider_account_id": "412833", "provider_account_secondary_id": "", "day": "2026-09-01", "scope": "[\"programmatic\",\"183920\",\"android\"]", "status": "covered", "accepted_at": "2026-09-02T04:12:51Z", "latest_status": null},
    {"provider": "liftoff", "provider_account_id": "8f14e45fceea167a5a36dedd4bea2543", "provider_account_secondary_id": "", "day": "2026-09-01", "scope": "customer-day", "status": "covered", "accepted_at": "2026-09-02T06:14:09Z", "latest_status": null},
    {"provider": "meta", "provider_account_id": "1029384756473829", "provider_account_secondary_id": "", "day": "2026-09-01", "scope": "business-day", "status": "covered", "accepted_at": "2026-09-02T08:40:17Z", "latest_status": "running"},
    {"provider": "moloco", "provider_account_id": "EXAMPLE_PLATFORM", "provider_account_secondary_id": "EXAMPLE_PUBLISHER", "day": "2026-09-01", "scope": "account-pair-day", "status": "covered", "accepted_at": "2026-09-02T05:03:44Z", "latest_status": null}
  ],
  "page": {"limit": 1000, "offset": 0, "has_more": false, "snapshot": "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c"}
}
```

该请求指定了 `day`、`provider` 和 `country`，并自动加入 `source_timezone` 和 `currency`。由于三个广告网络未上报币种，`fields` 还列出了广告网络账号列：Digital Turbine 行上报 `USD`，因此其账号列为 `null`。

| 字段           | 含义                                                    |
| ------------ | ----------------------------------------------------- |
| `query_time` | CloudX 读取该页的时间。                                       |
| `fields`     | 按输出顺序排列的行列名：先维度，后指标。                                  |
| `rows`       | 报表行。每个对象按 `fields` 的顺序，为每个条目提供一个键。                    |
| `coverage`   | 每个广告网络账号在所请求日期中哪些日期有数据。参见[覆盖情况](#覆盖情况)。               |
| `page`       | `limit`、`offset`、`has_more` 和 `snapshot`。参见[分页](#分页)。 |

### 覆盖情况

`coverage` 为每个广告网络账号、范围（scope）和所请求日期各提供一个条目。可用它区分没有流量的日期和 CloudX 尚未采集的日期。

| 字段                                                               | 含义                                                                                                       |
| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `provider`、`provider_account_id`、`provider_account_secondary_id` | 广告网络账号。                                                                                                  |
| `day`                                                            | 所请求的日期，`YYYY-MM-DD`。                                                                                     |
| `scope`                                                          | 广告网络独立上报的单元，例如一个 business、customer 或账号。Digital Turbine 按应用和平台分别上报。请将该值视为不透明值。                            |
| `status`                                                         | `covered` 表示该日期有数据，`empty` 表示广告网络上报了该日期但没有行，`missing` 表示 CloudX 尚无该日期的数据。                                |
| `accepted_at`                                                    | CloudX 存储该日期数据的时间。`status` 为 `missing` 时为 `null`。                                                        |
| `latest_status`                                                  | 该日期最近一次采集处于排队、进行中或失败状态时，分别为 `pending`、`running` 或 `failed`；否则为 `null`。刷新进行中时，`covered` 日期也可能为 `running`。 |

广告网络会在首次发布后修订近期日期的数据。CloudX 采集到修订后，会替换已存储的当日数据，`accepted_at` 随之改变。如果账号完全没有广告网络报表数据，`coverage` 只包含一个 `status: "missing"` 的条目，其账号和日期字段为空。

### 排序

未传入 `sort_by` 时，行按输出顺序中的每个分组列升序排列，`null` 值排在最后。分组列包括[收入币种](#收入币种)规则加入的广告网络账号列。

传入 `sort_by=revenue` 时，行按收入排序，默认降序，传入 `sort_order=asc` 时升序。无论哪个方向，收入为 `null` 的行都排在最后。收入相同时按分组列排序，因此分页边界是确定的。

### 分页

每页最多包含 `limit` 行，从跳过 `offset` 行之后开始。还有后续行时，`page.has_more` 为 `true`。超过最后一行的页面为空。

不传 `snapshot` 时，每一页都读取最新数据。如果 CloudX 在两页之间存储了某天的修订数据，行可能跨越分页边界移动。如需检测这种情况，请在后续每一页中将第一页的 `page.snapshot` 作为 `snapshot` 传入。snapshot 涵盖查询本身及其读取的已存储数据，但不包括 `limit`、`offset` 或 `format`。任一项发生变化时，请求返回 `409`。请从 `offset=0` 重新开始，且不传 `snapshot`。

```bash
#!/usr/bin/env bash
set -euo pipefail

url="https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&dimensions=day,provider,app_id,country&limit=1000"

offset=0
snapshot=""
: > rows.jsonl
while true; do
  status=$(curl -sS -o page.json -w '%{http_code}' \
    "$url&offset=$offset${snapshot:+&snapshot=$snapshot}" \
    -H "Authorization: Bearer $CLOUDX_API_KEY")
  if [ "$status" = 409 ]; then
    offset=0; snapshot=""; : > rows.jsonl; continue
  fi
  [ "$status" = 200 ] || { cat page.json >&2; exit 1; }

  jq -c '.rows[]' page.json >> rows.jsonl
  snapshot=$(jq -r '.page.snapshot' page.json)
  [ "$(jq -r '.page.has_more' page.json)" = true ] || break
  offset=$((offset + 1000))
done
```

### CSV 响应

`format=csv` 以 `text/csv` 返回相同的行。标题行与 `fields` 一致。分页和覆盖元数据移到响应头中。

```bash
curl -i "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-01&dimensions=day,provider,country&filter.country=us&format=csv" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

```text
HTTP/2 200
content-type: text/csv; charset=utf-8
x-network-query-time: 2026-09-02T09:30:00.123456Z
x-network-limit: 1000
x-network-offset: 0
x-network-has-more: false
x-network-snapshot: 50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c
x-network-coverage: [{"provider":"digitalturbine","provider_account_id":"412833","provider_account_secondary_id":"","covered":1,"empty":0,"missing":0,"latest_failed_scopes":0,"latest_pending_scopes":0,"latest_running_scopes":0,"oldest_accepted_at":"2026-09-02T04:12:51Z","latest_accepted_at":"2026-09-02T04:12:51Z"},…]

day,provider,provider_account_id,provider_account_secondary_id,country,source_timezone,currency,impressions,clicks,revenue,ecpm,average_cpc,missing_impressions,missing_clicks,missing_revenue
2026-09-01,digitalturbine,\N,\N,us,UTC,USD,15320,201,68.94,4.5,0.34298507462686567,0,0,0
2026-09-01,liftoff,8f14e45fceea167a5a36dedd4bea2543,,us,UTC,\N,48210,612,241.05,5,0.3938725490196079,0,0,0
2026-09-01,meta,1029384756473829,,us,America/Los_Angeles,\N,30500,305,152.5,5,0.5,0,0,0
2026-09-01,moloco,EXAMPLE_PLATFORM,EXAMPLE_PUBLISHER,us,UTC,\N,9140,88,41.13,4.5,0.46738636363636366,0,0,0
```

| 响应头                    | 含义                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------ |
| `X-Network-Query-Time` | 与 `query_time` 相同。                                                                                     |
| `X-Network-Limit`      | 与 `page.limit` 相同。                                                                                     |
| `X-Network-Offset`     | 与 `page.offset` 相同。                                                                                    |
| `X-Network-Has-More`   | 与 `page.has_more` 相同。                                                                                  |
| `X-Network-Snapshot`   | 与 `page.snapshot` 相同。同一查询的 JSON 页和 CSV 页共用同一个 snapshot。                                                |
| `X-Network-Coverage`   | JSON 数组，每个广告网络账号一条汇总：`covered`、`empty` 和 `missing` 的范围日数；最近一次采集为失败、排队或进行中的范围日数；以及最早和最晚的 `accepted_at`。 |

CSV 将 `null` 写为 `\N`，将空字符串写为空字段。以反斜杠开头的文本值会再加一个反斜杠，因此字面文本 `\N` 会写为 `\\N`。包含逗号、引号或换行符的字段会加引号。

如果覆盖汇总超出响应头的大小限制，请求返回 `422`。请改用 `format=json`，或按 `provider`、`provider_account_id` 或 `provider_account_secondary_id` 过滤。

### 请求示例

所有示例都使用基础 URL `https://provisioning.cloudx.io/api/v1`，并将 API key 作为 bearer token 发送。

#### 查询日期范围

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

每个日期和广告网络账号返回一行。

#### 按广告格式过滤

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&filter.format=rewarded" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

#### 按广告网络过滤

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&filter.provider=liftoff" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

#### 按国家/地区过滤

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&filter.country=us" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

#### 按应用包名过滤

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&filter.package=com.example.game" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

Meta 不上报包名，因此该过滤器会排除 Meta 的行。

#### 按平台过滤

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&filter.platform=ios" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

#### 按广告位过滤

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&filter.placement_id=PLACEMENT_ID" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

将 `PLACEMENT_ID` 替换为广告网络中的广告位或广告单元 ID。

#### 匹配同一维度的多个值

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&filter.country=us&filter.country=ca" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

返回美国或加拿大的行。

#### 组合多个维度的过滤器

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&filter.platform=ios&filter.country=us" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

返回美国的 iOS 行。

#### 按日拆分

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&dimensions=day" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

每个日期、币种和来源时区返回一行。未上报币种的广告网络还会按广告网络账号分别返回一行；参见[收入币种](#收入币种)。

#### 按日期、广告网络、应用和国家/地区拆分

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&dimensions=day,provider,app_id,country" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

#### 读取展示数、点击数、收入和 eCPM

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&dimensions=day" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

每个响应都包含全部[指标](#指标)；不提供指标选择参数。

#### 导出 CSV

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&format=csv" \
  -H "Authorization: Bearer $CLOUDX_API_KEY" \
  -o network.csv
```

#### 选择维度未知的行

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&is_null=package" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

返回 `package` 为 `null` 的行，包括全部 Meta 行。

#### 查找缺失指标和未完成的日期

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&format=json" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

`missing_impressions`、`missing_clicks` 或 `missing_revenue` 非零的行包含缺少该指标的广告网络报表行。`status: "missing"` 的 `coverage` 条目是 CloudX 尚未采集的日期。

#### 按收入排序

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&sort_by=revenue&sort_order=desc" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

`sort_order` 可选，默认为 `desc`。

#### 分页读取结果

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&limit=100&offset=100" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

返回第 101 至 200 行。`page.has_more` 为 `true` 时继续读取；CSV 请读取 `X-Network-Has-More`。

#### 基于一致的 snapshot 分页

```bash
curl "https://provisioning.cloudx.io/api/v1/reports/network?start_date=2026-09-01&end_date=2026-09-07&limit=100&offset=100&snapshot=SNAPSHOT" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"
```

将 `SNAPSHOT` 替换为第一页的 `page.snapshot`。返回 `409` 表示已存储的数据发生了变化；请从 `offset=0` 重新开始。

### 错误

错误以 JSON 返回，包含 `error` 消息，例如 `{"error": "invalid network report request: unknown dimension app"}`。

| 状态码   | 原因                                                                                                                         | 处理方式                                           |
| ----- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `400` | 未知参数或维度、重复或为空的参数、无效日期、`end_date` 早于 `start_date`、传入 `sort_order` 但未传 `sort_by`、格式错误的 `snapshot`，或对同一维度同时使用 `is_null` 和过滤器。 | 修正请求。错误消息会指出问题。                                |
| `401` | API key 缺失或无效。                                                                                                             | 发送有效的 key。                                     |
| `403` | key 缺少 `reports:read` 权限，或账号未启用广告网络报表。                                                                                     | 添加权限，或联系您的 CloudX 客户经理。                        |
| `409` | `snapshot` 与查询或已存储的数据不再匹配。                                                                                                 | 从 `offset=0` 重新开始，且不传 `snapshot`。              |
| `422` | 超出了某项[限制](#限制)。                                                                                                            | 缩小日期范围或过滤条件，减小 `limit` 或 `offset`，或等待其他报表请求完成。 |
| `503` | 报表数据正在更新。                                                                                                                  | 在 `Retry-After` 指定的时间后重试。                      |
| `504` | 报表未能及时完成。                                                                                                                  | 在 `Retry-After` 指定的时间后重试，或缩小日期范围或过滤条件。         |

### 限制

| 限制        | 值           |
| --------- | ----------- |
| 日期范围      | 90 天，包含首尾两天 |
| 每个过滤器的值数  | 100         |
| 每个过滤值的字节数 | 1,024       |
| 每页行数      | 10,000      |
| 偏移量       | 1,000,000   |
| 响应大小      | 32 MiB      |
| 请求时长      | 30 秒        |

如果请求读取的报表数据过多，或在过多报表请求运行时到达，也会返回 `422`。请逐个发送报表请求。