report/breakdown

GET/report/breakdown

Fetch grouped reporting rows for the requested time range. Requires the reports:read permission.

Request

cURL

curl -X GET "https://provisioning.cloudx.io/api/v1/report/breakdown?start_time=1712448000&end_time=1712534399&by=day,app&metrics=requests,impressions,revenue" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"

Query parameters

Name	Type	Description
`timezone`	`string`	IANA timezone for calendar buckets. Defaults to UTC. start_time and end_time remain absolute Unix timestamps and are never shifted. SDK reports, hourly dashboard/breakdown reports, and breakdowns grouped by bidder require whole-hour timezone offsets throughout the requested window because of hourly data and bucketing limitations. A/B reports support UTC only because they use saved UTC-day totals.
`start_time`required	`integer<int64>`	Start of the time range as a Unix timestamp in seconds. The requested range must not exceed 31 days and must not start before 2020-01-01 UTC.
`end_time`required	`integer<int64>`	End of the time range as a Unix timestamp in seconds. The requested range must not exceed 31 days and must not end before 2020-01-01 UTC.
`by`required	`string`	Comma-separated breakdown dimensions. Supported values are `hour`, `day`, `week`, `month`, `country`, `os`, `app`, `ad_unit`, `format`, and `bidder`. The `bidder` dimension is available for periods beginning on or after 2026-06-01.
`metrics`required	`string`	Comma-separated metric names to include in each breakdown row. Supported values are `requests`, `bid_requests`, `fills`, `impressions`, `revenue`, `fill_rate`, `ecpm`, `clicks`, and `ctr`. `requests` always counts ad requests. In a bidder breakdown, it repeats for each bidder in the same dimension group and must not be summed across bidders. `bid_requests` counts requests sent to the bidder and requires the `bidder` dimension. `fills`, `impressions`, `revenue`, and `clicks` are attributed to the bidder and can be summed across bidder rows.
`test_mode`	`string`	Traffic mode to include. Defaults to production traffic. Allowed values: production, test, all.
`country`	`string`	ISO 3166-1 alpha-2 country code filter.
`device_os`	`string`	Device operating system filter. Allowed values: iOS, Android.
`granularity`	`string`	Reporting bucket size. Defaults to daily. Allowed values: daily, hourly.
`top`	`integer<int32>`	Return the top N rows sorted by the first requested metric.
`bottom`	`integer<int32>`	Return the bottom N rows sorted by the first requested metric.
`having`	`string`	Metric filter expression, such as `revenue > 10`.

Responses

CloudX breakdown data.

{
  "dimensions": [
    "<string>"
  ],
  "metrics": [
    "<string>"
  ],
  "rows": [
    {
      "dimensions": {},
      "metrics": {}
    }
  ],
  "row_count": 123
}

200CloudX breakdown data.

Field	Type	Description
`dimensions`required	`array of string`
`metrics`required	`array of string`
`rows`required	`array of object`
`row_count`required	`integer<int64>`

400Invalid request parameters.

Field	Type	Description
`error`required	`string`

401Unauthorized.

Field	Type	Description
`error`required	`string`

403Forbidden.

Field	Type	Description
`error`required	`string`

500Internal server error.

Field	Type	Description
`error`required	`string`

504The query did not finish within the request time budget. Retry, narrowing the time range or filters where the operation accepts them.

Field	Type	Description
`error`required	`string`

拆分报表参考

by 和 metrics 是必填的逗号分隔列表。校验前名称不区分大小写。每个列表至少要有一个唯一的受支持名称。最多可请求四个维度。

`by` 值	结果键和值
`hour`	UTC RFC 3339 小时桶。需要 `granularity=hourly`。
`day`	UTC 日历日期。
`week`	从周日开始的 UTC 周桶。
`month`	UTC 月桶。
`country`	设备国家。
`os`	设备操作系统。
`app`	CloudX 应用 bundle 或应用标识。
`ad_unit`	CloudX 广告单元 ID。
`format`	CloudX 广告格式。
`bidder`	CloudX 竞价方 ID。时间范围必须从 2026-06-01 或之后开始。

`metrics` 值	结果键和值
`requests`	广告请求数。使用 `bidder` 时，该值会在同一其他维度组的每个竞价方行中重复。不要跨竞价方行求和。
`bid_requests`	发给竞价方的请求数。需要 `bidder`。
`fills`	已填充广告请求数。使用 `bidder` 时为该竞价方的胜出出价数。
`impressions`	CloudX 展示数。
`revenue`	CloudX 确认的收入。
`fill_rate`	`(impressions / requests) * 100`，不是比率值。
`ecpm`	`revenue * 1000 / impressions`。
`clicks`	点击数。
`ctr`	`(clicks / impressions) * 100`，不是比率值。

CloudX 根据每个返回行的汇总组件计算比率指标，不会平均已计算的比率。可以跨竞价方行汇总 bid_requests、fills、impressions、revenue 和 clicks。一个请求可以邀请多个竞价方，所以 requests 不能按竞价方相加。

响应包含 dimensions、metrics、rows 和 row_count。dimensions 和 metrics 会重复已接受的请求名称。每个 rows[] 对象都有 dimensions 字符串 map 和 metrics 数字 map。map 只包含请求的名称。row_count 是返回行数。CloudX 最多返回 100,000 行。

test_mode 为 production、test 或 all，默认 production。device_os 为 iOS 或 Android。granularity 为 daily 或 hourly，默认 daily。country 是 ISO 3166-1 alpha-2 过滤器。top 和 bottom 都允许 1 至 1000，按第一个请求的指标排序，不能同时使用。having 接受一个受支持指标、操作符 <、<=、=、==、!=、>= 或 > 以及数字。API 时间范围使用包含端点的 Unix 秒，不早于 2020-01-01 UTC，且最多 31 天。

JSON 示例

{
  "dimensions": ["day", "country"],
  "metrics": ["revenue", "impressions", "ecpm"],
  "rows": [{"dimensions": {"day": "2026-04-01", "country": "US"}, "metrics": {"revenue": 14.25, "impressions": 1200, "ecpm": 11.875}}],
  "row_count": 1
}