Reporting

Available commands:

cloudx report dashboard for summary and daily or hourly metrics
cloudx report breakdown for CloudX-only custom breakdowns by time, inventory, and device dimensions
cloudx report bidders for bidder performance
cloudx report apps for app performance
cloudx report ad-units for ad unit performance
cloudx report export for CSV or JSON export
cloudx report impressions export for asynchronous, impression-level revenue exports

Request Timeout

Reporting requests default to a 60 second API timeout. Use the global --timeout flag before the command when a workflow should fail earlier, or when a heavy report needs more time.

cloudx --timeout 90s report export --period 2026-04-01..2026-04-07

--timeout accepts duration values such as 30s, 90s, or 2m. Values must be greater than 0s and no more than 2m.

Shared Flags

Most reporting commands use the flags below. Exact support by command is listed in the next section.

Flag	Required	Description
`--period`	No	Time range. Defaults to `today`. Supports `today`, `yesterday`, `last_7d`, `last_30d`, `YYYY-MM-DD`, or `YYYY-MM-DD..YYYY-MM-DD`.
`--granularity`	No	Report bucket granularity. Supported by `report dashboard`, `report breakdown`, and `report export`. Allowed values: `daily`, `hourly`. Default: `daily`.
`--test-mode`	No	Test filter. Allowed values: `production`, `test`, `all`. Default: `production`.
`--app`	No	App bundle filter. Supported by `report ad-units` and `report impressions export`.
`--ad-unit-type`	No	Ad unit type filter. Only supported by `report ad-units`. Allowed values: `BANNER`, `INTERSTITIAL`, `REWARDED`, `MREC`, `NATIVE`.
`--country`	No	ISO-2 country code, for example `US` or `GB`.
`--device-os`	No	Device platform filter. Allowed values: `iOS`, `Android`.
`--source`	No	Report source filter. Supported by `report dashboard`, `report apps`, and `report ad-units`. Defaults to CloudX when omitted.
`--json`	No	Emit structured JSON instead of human-readable output.

Flag Support By Command

Flag	Dashboard	Breakdown	Bidders	Apps	Ad Units	Export	Impression Export
`--period`	✅	✅	✅	✅	✅	✅	❌
`--granularity`	✅	✅	❌	❌	❌	✅	❌
`--test-mode`	✅	✅	✅	✅	✅	❌	✅
`--app`	❌	❌	❌	❌	✅	❌	✅
`--ad-unit-type`	❌	❌	❌	❌	✅	❌	❌
`--country`	✅	✅	✅	✅	✅	✅	✅
`--device-os`	✅	✅	✅	✅	✅	✅	✅
`--source`	✅	❌	❌	✅	✅	❌	❌
`--json`	✅	✅	✅	✅	✅	✅	❌

Period Values

Period parsing is UTC-based. If you omit --period, every reporting command uses today.

Value	Meaning
`today`	Current UTC day
`yesterday`	Previous UTC day
`last_7d`	Current UTC day plus the previous 6 days
`last_30d`	Current UTC day plus the previous 29 days
`2026-04-01`	Single UTC day
`2026-04-01..2026-04-07`	Inclusive UTC date range

Validation rules:

End date must not be earlier than start date.
--country must be a two-letter uppercase ISO-2 code after normalization.
--device-os must be exactly iOS or Android.
--test-mode must be production, test, or all.
--granularity must be daily or hourly.

Granularity Values

Use --granularity when you need to change how reporting rows are bucketed inside the selected period.

Value	Meaning
`daily`	UTC calendar-day buckets. This is the default.
`hourly`	UTC hour buckets. Supported by `report dashboard`, `report breakdown`, and `report export`.

For hourly dashboard reports, the human-readable chart table uses BUCKET START instead of DATE, and JSON chart rows include bucket_start timestamps such as 2026-04-01T13:00:00Z. For hourly exports, the leading CSV or JSON column changes from date to bucket_start.

Source Values

When you omit --source, report commands use the existing CloudX-only reporting path. This keeps dashboard, app, and ad-unit results scoped to impressions served by CloudX. Use --source when you want reports to include impression-level revenue data (ILRD) forwarded by publisher SDKs for other mediation platforms.

Value	Meaning
`cloudx`	CloudX-served impressions only.
`<mediator>`	A mediator/platform source from external ILRD, such as `applovin`.
`cloudx,applovin`	A comma-separated comparison across specific sources.
`all`	CloudX plus every available external mediator source.

Source names are case-insensitive and normalized by the CLI. External source values come from the ILRD mediator/platform, not the downstream demand network. For example, AppLovin MAX rows with ADMOB_BIDDING demand are reported under applovin, not admob.

When --source includes external mediators, fill rate remains CloudX-only because external ILRD includes impressions and revenue, but not CloudX bid requests. The CLI labels this as Fill Rate (CloudX-only).

Output Format

Human-Readable

Most commands print a metadata block first, then a table. Example metadata block:

Period:      last_30d
Test mode:   production
Country:     US
Device OS:   iOS
Granularity: hourly

JSON

Pass --json to return structured JSON:

cloudx report dashboard --json

All command examples are collected on the Examples page.

`cloudx report dashboard`

Shows summary metrics and daily or hourly chart rows.

Usage

cloudx report dashboard [--period <value>] [--granularity daily|hourly] [flags]

Use --source all to include external mediator ILRD in dashboard revenue, impressions, eCPM, and source breakdowns:

cloudx report dashboard --period last_7d --source all

Use --granularity hourly to show chart rows by UTC hour:

cloudx report dashboard --period 2026-04-01 --granularity hourly

Example

$ cloudx report dashboard
Period:      today
Test mode:   production

Requests:     1.5M
Impressions:  1.2M
Revenue:      $14.9K
Fill Rate:    78.0%
eCPM:         $12.7
Clicks:       35.1K
CTR:          3.0%
Users:        42K

DATE        REQUESTS  IMPRESSIONS  REVENUE  CLICKS
2026-03-29  210K      163.8K       $2.1K    4.9K

`cloudx report breakdown`

Shows CloudX-only aggregate metrics grouped by the dimensions you choose. This command is intended for ad hoc analysis such as revenue by country, hourly fill rate by app, or eCPM by ad unit. It does not accept --source and does not include external mediator ILRD or provider revenue. Use the source-aware dashboard, app, and ad-unit commands only when you need external ILRD where supported.

Usage

cloudx report breakdown --by <dimensions> --metrics <metrics> [flags]

Dimensions

Use a comma-separated list with --by.

Dimension	Meaning
`hour`	UTC hour bucket. Requires `--granularity hourly`.
`day`	UTC calendar day.
`week`	UTC week bucket starting on Sunday.
`month`	UTC month bucket.
`country`	Device country.
`os`	Device operating system.
`app`	App bundle or app identifier from CloudX reporting.
`ad_unit`	CloudX ad unit ID.
`format`	CloudX ad type/format.

Metrics

Use a comma-separated list with --metrics.

Metric	Meaning
`requests`	CloudX request count.
`impressions`	CloudX impression count.
`revenue`	CloudX revenue.
`fill_rate`	`impressions / requests`.
`ecpm`	`revenue * 1000 / impressions`.
`clicks`	Click count.
`ctr`	`clicks / impressions`.

Rate metrics are computed from summed components for each returned row. They are not averaged from precomputed rates.

Options

Flag	Description
`--granularity daily`	Default. Use daily-compatible time dimensions such as `day`, `week`, or `month`.
`--granularity hourly`	Enables UTC hour buckets and the `hour` dimension.
`--top N`	Return the top `N` rows sorted by the first requested metric.
`--bottom N`	Return the bottom `N` rows sorted by the first requested metric.
`--having <expr>`	Filter rows by a metric expression, for example `revenue > 10`.

Having Expressions

--having filters rows after grouping. It supports one metric comparison:

<metric> <operator> <number>

Supported operators: <, <=, =, ==, !=, >=, >. The metric must be one of the supported breakdown metrics listed above, and the right-hand side must be a number. == is accepted as an alias for =. Boolean logic, strings, SQL functions, and field-to-field comparisons are not supported. Valid examples:

--having 'revenue > 10'
--having 'impressions >= 1000'
--having 'ctr < 1.5'

Invalid examples:

--having 'revenue > 10 OR 1=1'
--having 'country = US'
--having 'revenue > impressions'

Examples

Daily revenue, impressions, and eCPM by country:

cloudx report breakdown --period last_7d --by day,country --metrics revenue,impressions,ecpm

Hourly app fill rate for one day:

cloudx report breakdown --period 2026-04-01 --granularity hourly --by hour,app --metrics requests,impressions,fill_rate

Top ad units by revenue:

cloudx report breakdown --by app,ad_unit --metrics revenue,ecpm --top 10

JSON output filtered by a metric threshold:

cloudx report breakdown --by country --metrics revenue,impressions --having 'revenue > 10' --json

Example Output

$ cloudx report breakdown --period 2026-04-01 --granularity hourly --by hour,country --metrics revenue,impressions,ecpm
Period:       2026-04-01
Test mode:    production
Granularity:  hourly

HOUR                  COUNTRY  REVENUE  IMPRESSIONS  ECPM
2026-04-01T00:00:00Z  US       $128.4   10.2K        $12.6
2026-04-01T01:00:00Z  GB       $84.1    6.8K         $12.4

`cloudx report bidders`

Shows bidder-level performance for the selected time period.

Usage

cloudx report bidders [--period <value>] [flags]

Example

$ cloudx report bidders
Period:      today
Test mode:   production

BIDDER  REQUESTS  BIDS  BID RATE  IMPRESSIONS  WIN RATE  REVENUE  ECPM
meta    850K      629K  74.0%     314.5K       50.0%     $5.6K    $17.7

`cloudx report apps`

Shows app-level performance for the selected time period.

Usage

cloudx report apps [--period <value>] [flags]

Use a comma-separated source list to compare CloudX against a mediator for each app:

cloudx report apps --period last_30d --source cloudx,applovin

Example

$ cloudx report apps
Period:      today
Test mode:   production

APP ID            NAME          PLATFORM  IMPRESSIONS  FILL RATE  REVENUE  ECPM
com.example.game  Example Game  iOS       1.8M         78.0%      $8.4K    $4.7

`cloudx report ad-units`

Shows ad-unit-level performance for the selected time period.

Usage

cloudx report ad-units [--period <value>] [flags]

This is the only reporting command that currently supports both --app and --ad-unit-type. Use --source all with --app to see CloudX and external mediator revenue for the same app’s ad units:

cloudx report ad-units --app com.example.game --source all

Example

$ cloudx report ad-units
Period:      today
Test mode:   production

AD UNIT ID  NAME                APP NAME      APP BUNDLE        TYPE    IMPRESSIONS  FILL RATE  REVENUE  ECPM
abc123      Home Screen Banner  Example Game  com.example.game  BANNER  450K         55.0%      $2.1K    $4.7

`cloudx report export`

Exports report data in CSV format by default.

Usage

cloudx report export [--period <value>] [--granularity daily|hourly] [flags]

Use --granularity hourly when downstream reporting needs UTC hour buckets:

cloudx report export --period 2026-04-01 --granularity hourly

Example

$ cloudx report export
date,network_name,country
2026-03-29,meta,US

Hourly exports use bucket_start for the first column:

$ cloudx report export --period 2026-03-29 --granularity hourly
bucket_start,network_name,country
2026-03-29T13:00:00Z,meta,US

JSON Output

With --json, the response includes:

columns
rows
row_count

`cloudx report impressions export`

Creates a full-day, impression-level revenue export as a gzip-compressed CSV file. The export runs asynchronously so large result sets do not have to fit within a normal API request.

Usage

cloudx report impressions export --date YYYY-MM-DD [filters] [--wait] [--output <path>]

--date is required and must identify a completed UTC day within the previous 45 days. The current UTC day cannot be exported because it is not complete.

Options

Flag	Required	Description
`--date`	Yes	Completed UTC day in `YYYY-MM-DD` format. Must be within the previous 45 days.
`--app-id`	No	CloudX app ID. Cannot be combined with `--app`.
`--app`	No	App bundle, for example `com.example.game`. Cannot be combined with `--app-id`.
`--ad-unit-id`	No	CloudX ad unit ID.
`--country`	No	ISO 3166-1 alpha-2 country code, for example `US` or `GB`.
`--device-os`	No	Device OS. Allowed values: `iOS`, `Android`.
`--bidder`	No	Bidder/network code.
`--line-item-id`	No	CloudX line item ID.
`--test-mode`	No	Traffic to include: `production`, `test`, or `all`. Default: `production`.
`--wait`	No	Poll until the export is ready or failed. The wait can run for up to 2 hours and 15 minutes.
`--output`	No	Download the ready `.csv.gz` file to this path. Implies `--wait`.

Only two impression exports may be processing for an account at the same time. Submitting the same date and filters again reuses the matching queued, running, or completed export instead of creating duplicate work. When an export is ready, CloudX returns a download URL that expires after one hour. Re-running the same command can issue a fresh URL while the generated file is still retained. Generated files are retained for up to seven days.

Impression exports can contain advertising identifiers, inventory metadata, and raw revenue data. Store downloaded files securely, restrict access to authorized users, and delete files when they are no longer needed.

Examples

Queue an export and print its export ID and current status:

cloudx report impressions export --date 2026-07-16

Wait for completion and download the result:

cloudx report impressions export \
  --date 2026-07-16 \
  --output ./impressions-2026-07-16.csv.gz

Export production impressions for one iOS app in the United States:

cloudx report impressions export \
  --date 2026-07-16 \
  --app com.example.game \
  --country US \
  --device-os iOS \
  --test-mode production \
  --output ./example-game-us-ios.csv.gz

Check the downloaded archive and preview its header and first rows:

gzip -t ./impressions-2026-07-16.csv.gz
gzip -cd ./impressions-2026-07-16.csv.gz | head

CSV Schema

The CSV contains one row per matching impression. Row order is not guaranteed.

Column	Description
`event_time`	Impression event time in UTC.
`impression_id`	Unique impression event ID.
`auction_id`	Related auction ID.
`bid_id`	Winning bid ID.
`app_id`	CloudX app ID.
`app_bundle`	App bundle or package name.
`ad_unit_id`	CloudX ad unit ID.
`ad_unit_name`	Ad unit display name.
`ad_format`	Ad format recorded for the impression.
`placement`	Publisher placement value.
`custom_data`	Publisher-provided custom data.
`country`	Uppercase ISO country code.
`device_os`	Device operating system.
`device_type`	Device type recorded for the impression.
`advertising_id`	Device advertising identifier, when available.
`advertising_vendor_id`	Vendor identifier, when available.
`test_mode`	`true` for test traffic; `false` for production traffic.
`network`	Bidder/network code.
`line_item_id`	CloudX line item ID.
`price_cpm`	Winning price expressed as CPM.
`revenue_usd`	Revenue for this individual impression in USD.
`currency`	Revenue currency. Currently `USD`.
`revenue_precision`	Revenue precision. Currently `exact`.
`creative_id`	Creative ID, when available.
`network_placement_id`	Network-side placement ID, when available.
`ab_test_id`	A/B test ID, when applicable.
`ab_test_variant`	A/B test variant, when applicable.

​Reporting

​Request Timeout

​Shared Flags

​Flag Support By Command

​Period Values

​Granularity Values

​Source Values

​Output Format

​Human-Readable

​JSON

​cloudx report dashboard

​Usage

​Example

​cloudx report breakdown

​Usage

​Dimensions

​Metrics

​Options

​Having Expressions

​Examples

​Example Output

​cloudx report bidders

​Usage

​Example

​cloudx report apps

​Usage

​Example

​cloudx report ad-units

​Usage

​Example

​cloudx report export

​Usage

​Example

​JSON Output

​cloudx report impressions export

​Usage

​Options

​Examples

​CSV Schema

​Related

Reporting

Request Timeout

Shared Flags

Flag Support By Command

Period Values

Granularity Values

Source Values

Output Format

Human-Readable

JSON

`cloudx report dashboard`

Usage

Example

`cloudx report breakdown`

Usage

Dimensions

Metrics

Options

Having Expressions

Examples

Example Output

`cloudx report bidders`

Usage

Example

`cloudx report apps`

Usage

Example

`cloudx report ad-units`

Usage

Example

`cloudx report export`

Usage

Example

JSON Output

`cloudx report impressions export`

Usage

Options

Examples

CSV Schema

Related