reports/network

GET/reports/network

Read daily ad network reporting collected from your connected data sources, grouped by the dimensions you choose, with impressions, clicks, revenue, eCPM, and average CPC. Requires the reports:read permission and network reporting access for the account. Match exact values with repeated filter.<dimension> parameters, and select unknown values with is_null. source_timezone and currency always group. Rows from a network that does not report its currency also keep provider, provider_account_id, and provider_account_secondary_id, so revenue in different currencies is never summed. Impression, click, and missing counts are decimal strings. Pass the first page's page.snapshot as snapshot to detect data changes between pages.

维度列表

在 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`	收入币种。始终包含。

Request

cURL

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

Query parameters

Name	Type	Description
`start_date`required	`string<date>`	First report day, `YYYY-MM-DD`. The range covers at most 90 days, inclusive.
`end_date`required	`string<date>`	Last report day, `YYYY-MM-DD`, inclusive. Must not precede `start_date`.
`dimensions`	`string`	Comma-separated breakdown. Defaults to `day,provider,provider_account_id,provider_account_secondary_id`. Accepts `day`, `provider`, `provider_account_id`, `provider_account_secondary_id`, `account_name`, `property_id`, `app_id`, `app_name`, `package`, `store_id`, `platform`, `country`, `format`, `placement_id`, `placement_reference_id`, `placement_name`, `ad_size`, `incentivized`, `original_platform`, `original_format`, `source_timezone`, and `currency`. Output column order is fixed, whatever the request order. 维度列表
`filter.day`	`array of string<date>`	Report day, `YYYY-MM-DD`. Repeat to match any of several values. 维度列表
`filter.provider`	`array of string`	Ad network. Repeat to match any of several values. Allowed values: digitalturbine, inmobi, liftoff, meta, moloco. 维度列表
`filter.provider_account_id`	`array of string`	Network account ID from the data source connection. Repeat to match any of several values. 维度列表
`filter.provider_account_secondary_id`	`array of string`	Moloco publisher ID; empty string for other networks. Repeat to match any of several values. 维度列表
`filter.account_name`	`array of string`	CloudX account name. Repeat to match any of several values. 维度列表
`filter.property_id`	`array of string`	Meta property ID. Repeat to match any of several values. 维度列表
`filter.app_id`	`array of string`	The network's app ID. Repeat to match any of several values. 维度列表
`filter.app_name`	`array of string`	The network's app name. Repeat to match any of several values. 维度列表
`filter.package`	`array of string`	Android package or iOS bundle ID, such as `com.example.game`. Repeat to match any of several values. 维度列表
`filter.store_id`	`array of string`	App store ID, such as a numeric App Store ID. Repeat to match any of several values. 维度列表
`filter.platform`	`array of string`	Normalized platform. Repeat to match any of several values. Allowed values: android, ios, fireos. 维度列表
`filter.country`	`array of string`	Lowercase ISO 3166-1 alpha-2 country code, such as `us`. Repeat to match any of several values. 维度列表
`filter.format`	`array of string`	Normalized ad format. Repeat to match any of several values. Allowed values: banner, interstitial, native, rewarded. 维度列表
`filter.placement_id`	`array of string`	The network's placement or ad-unit ID. Repeat to match any of several values. 维度列表
`filter.placement_reference_id`	`array of string`	Liftoff placement reference ID. Repeat to match any of several values. 维度列表
`filter.placement_name`	`array of string`	The network's placement or ad-unit name. Repeat to match any of several values. 维度列表
`filter.ad_size`	`array of string`	Liftoff ad size, such as `320x50`. Repeat to match any of several values. 维度列表
`filter.incentivized`	`array of string`	Liftoff rewarded traffic flag. Allowed values: true, false. 维度列表
`filter.original_platform`	`array of string`	Platform exactly as the network reported it. Repeat to match any of several values. 维度列表
`filter.original_format`	`array of string`	Ad format exactly as the network reported it. Repeat to match any of several values. 维度列表
`filter.source_timezone`	`array of string`	Time zone that defines the network's report day. Allowed values: UTC, America/Los_Angeles. 维度列表
`filter.currency`	`array of string`	Revenue currency reported by the network, such as `USD`. Repeat to match any of several values. 维度列表
`is_null`	`array of string`	Select rows whose dimension value is unknown. Repeat for several dimensions. Cannot be combined with a `filter.<dimension>` for the same dimension. Allowed values: day, provider, provider_account_id, provider_account_secondary_id, account_name, property_id, app_id, app_name, package, store_id, platform, country, format, placement_id, placement_reference_id, placement_name, ad_size, incentivized, original_platform, original_format, source_timezone, currency. 维度列表
`sort_by`	`string`	Sort by aggregate revenue. Without it, rows sort ascending by every grouping column, unknown values last. Allowed values: revenue.
`sort_order`	`string`	Revenue sort direction; requires `sort_by`. Unknown revenue sorts last in both directions, and grouping columns break ties. Allowed values: desc, asc.
`limit`	`integer`	Rows per page.
`offset`	`integer`	Rows to skip before the page starts.
`snapshot`	`string`	The `page.snapshot` value from the first page. A later page returns 409 if the query or the report data changed; restart from `offset=0`.
`format`	`string`	Response format. CSV returns page and coverage metadata in `X-Network-*` headers. Allowed values: json, csv.

Responses

One page of report rows with per-source coverage. A page past the last row is empty.

{
  "query_time": "<string>",
  "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": "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"
    }
  ],
  "coverage": [
    {
      "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
    }
  ],
  "page": {
    "limit": 123,
    "offset": 123,
    "has_more": true,
    "snapshot": "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c"
  }
}

200 One page of report rows with per-source coverage. A page past the last row is empty.

Field	Type	Description
`query_time`required	`string<date-time>`	When the page was read.
`fields`required	`array of string`	Row columns in output order, dimensions first, then metrics.
`rows`required	`array of object`	Report rows keyed by `fields`. Unknown values are `null`.
`coverage`required	`array of object`	One entry per network account, scope, and requested day.
`page`required	`object`	Pagination state.

400 Invalid parameter, date, dimension, or filter.

Field	Type	Description
`error`required	`string`

401 Unauthorized.

Field	Type	Description
`error`required	`string`

403 Missing the `reports:read` permission or network reporting access.

Field	Type	Description
`error`required	`string`

409 The snapshot no longer matches; restart from `offset=0` without `snapshot`.

Field	Type	Description
`error`required	`string`

422 A report limit was exceeded. Narrow the dates or filters, or reduce `limit` or `offset`.

Field	Type	Description
`error`required	`string`

500 Internal server error.

Field	Type	Description
`error`required	`string`

503 Report data is being updated. Retry after the `Retry-After` delay.

Field	Type	Description
`error`required	`string`

504 The report did not finish in time. Retry after the `Retry-After` delay, or narrow the dates or filters.

Field	Type	Description
`error`required	`string`

广告网络报表参考

该端点返回广告网络发布的每日报表，数据由 CloudX 从 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`	十进制字符串	该分组中缺少收入的广告网络报表行数。

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

JSON 响应

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"

{
  "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。

#!/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 一致。分页和覆盖元数据移到响应头中。

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"

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 发送。

查询日期范围

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"

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

按广告格式过滤

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"

按广告网络过滤

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"

按国家/地区过滤

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"

按应用包名过滤

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 的行。

按平台过滤

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"

按广告位过滤

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。

匹配同一维度的多个值

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"

返回美国或加拿大的行。

组合多个维度的过滤器

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 行。

按日拆分

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"

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

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

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

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

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

选择维度未知的行

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 行。

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

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 尚未采集的日期。

按收入排序

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。

分页读取结果

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 分页

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。请逐个发送报表请求。