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
`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
}

200 CloudX 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>`

400 Invalid request parameters.

Field	Type	Description
`error`required	`string`

401 Unauthorized.

Field	Type	Description
`error`required	`string`

403 Forbidden.

Field	Type	Description
`error`required	`string`

500 Internal server error.

Field	Type	Description
`error`required	`string`

Breakdown reference

by and metrics are required comma-separated lists. Names are case-insensitive before validation. Each list must contain at least one unique supported name. You can request at most four dimensions.

`by` value	Result key and meaning
`hour`	UTC RFC 3339 hour bucket. Requires `granularity=hourly`.
`day`	UTC calendar date.
`week`	UTC week bucket that starts on Sunday.
`month`	UTC month bucket.
`country`	Device country.
`os`	Device operating system.
`app`	CloudX app bundle or app identifier.
`ad_unit`	CloudX ad-unit ID.
`format`	CloudX ad format.
`bidder`	CloudX bidder ID. The range must start on or after 2026-06-01.

`metrics` value	Result key and meaning
`requests`	Ad request count. With `bidder`, this count repeats for each bidder in the same other-dimension group. Do not sum it across bidder rows.
`bid_requests`	Requests sent to the bidder. Requires `bidder`.
`fills`	Filled ad requests. With `bidder`, this is the bidder’s winning-bid count.
`impressions`	CloudX impression count.
`revenue`	CloudX-recognized revenue.
`fill_rate`	`(impressions / requests) * 100`, not a ratio.
`ecpm`	`revenue * 1000 / impressions`.
`clicks`	Click count.
`ctr`	`(clicks / impressions) * 100`, not a ratio.

CloudX calculates rate metrics from the summed components of each returned row. It does not average stored rates. You can sum bid_requests, fills, impressions, revenue, and clicks across bidder rows. A request can invite multiple bidders, so requests is not bidder-additive.

The response has dimensions, metrics, rows, and row_count. dimensions and metrics repeat the accepted request names. Each rows[] object has a dimensions string map and a metrics number map. The maps contain only the requested names. row_count is the number of returned rows. CloudX returns at most 100,000 rows.

test_mode is production, test, or all. It defaults to production. device_os is iOS or Android. granularity is daily or hourly, and defaults to daily. country is an ISO 3166-1 alpha-2 filter. top and bottom each allow 1 through 1000, sort by the first requested metric, and cannot be combined. having accepts one supported metric, an operator from <, <=, =, ==, !=, >=, >, and a number. The API range is inclusive Unix seconds, starts no earlier than 2020-01-01 UTC, and spans at most 31 days.

JSON example

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