report/export

GET/report/export

Fetch CSV-schema export rows for the requested time range. Requires the reports:read permission.

Request

cURL

curl -X GET "https://provisioning.cloudx.io/api/v1/report/export?start_time=1712448000&end_time=1712534399" \
  -H "Authorization: Bearer $CLOUDX_API_KEY"

Query parameters

Name	Type	Description
`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.
`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.

Responses

CSV-schema export rows.

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

200CSV-schema export rows.

Field	Type	Description
`columns`required	`array of string`
`rows`required	`array of array of string`
`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`

导出响应参考

rows 是字符串数组的数组。每一行按 columns 中相同的位置取值。row_count 是返回行数。CloudX 最多返回 100,000 行。请求范围使用 Unix 秒且包含端点，开始时间不得早于 2020-01-01 UTC，范围不得超过 31 天。

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

位置	列	字符串值
1	`date`	UTC 日历日期，格式 `YYYY-MM-DD`。
2	`network_name`	动态买方适配器名称；CloudX 结算时为 `CloudX Exchange`。
3	`app_name`	广告单元匹配时由实时配置补充的应用名称；否则为源文本。
4	`app_store_id`	广告单元匹配时由实时配置补充的应用 bundle ID，并非总是数字商店 ID。
5	`platform`	源平台文本。大小写不规范化，例如 `android` 或 `iOS`。
6	`ad_unit_id`	动态 CloudX 广告单元 ID。
7	`ad_type`	广告单元匹配实时配置时的小写配置广告单元类型，例如 `banner`、`interstitial`、`rewarded`、`mrec` 或 `native`。
8	`network_placement`	已配置时为活动网络映射的 `placement_id`；否则为空字符串。
9	`country`	ISO 3166-1 alpha-2 国家代码；不可用时为空字符串。
10	`impressions`	十进制整数展示数。
11	`clicks`	十进制整数点击数。
12	`revenue`	恰有两位小数的十进制货币金额。
13	`attempts`	十进制整数请求数。
14	`responses`	十进制整数响应或填充数。

每小时导出只替换位置 1。该列为 bucket_start，值是 RFC 3339 UTC 时间戳，例如 2026-04-01T13:00:00Z。位置 2 至 14 不变。

device_os 只接受 iOS 或 Android。它过滤源数据，不会规范化返回的 platform 文本。country 按 ISO alpha-2 代码过滤。该端点只返回生产数据，且没有 test_mode 参数。network_name、应用 ID、广告单元 ID 和 placement ID 取决于配置和数据，不是固定枚举。

attempts 和 responses 取决于报表来源。旧报表使用 SSP 请求总数作为 attempts，并为 responses 返回 0。SDK 报表使用广告请求总数作为 attempts，使用填充总数作为 responses。

每日 JSON 示例

{
  "columns": ["date", "network_name", "app_name", "app_store_id", "platform", "ad_unit_id", "ad_type", "network_placement", "country", "impressions", "clicks", "revenue", "attempts", "responses"],
  "rows": [["2026-04-01", "CloudX Exchange", "Sample Puzzle", "com.example.puzzle", "iOS", "ad-unit-home", "banner", "", "US", "1200", "18", "14.25", "1500", "960"]],
  "row_count": 1
}

每小时 JSON 示例

{
  "columns": ["bucket_start", "network_name", "app_name", "app_store_id", "platform", "ad_unit_id", "ad_type", "network_placement", "country", "impressions", "clicks", "revenue", "attempts", "responses"],
  "rows": [["2026-04-01T13:00:00Z", "meta", "Sample Puzzle", "com.example.puzzle", "iOS", "ad-unit-home", "banner", "home-banner", "US", "120", "2", "1.43", "150", "96"]],
  "row_count": 1
}