Public reference for cloudx report commands, including filters, supported flags, and output formats.

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 demand-comparison for CloudX and partner demand totals
• cloudx report demand-comparison-ad-units for mapped or unmapped partner ad units
• cloudx report export for CSV or JSON export

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. Demand Comparison uses a focused flag set because it compares completed partner reports instead of live delivery data.

Flag support by command

Period Values

Standard reporting periods default to UTC. From CLI 0.41, use --timezone on supported commands to select another timezone. If you omit --period, these commands use today.

Demand Comparison uses completed calendar dates in --timezone. It has a separate default and validation rules described below.

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.

Reporting Timezones

From CLI 0.41, report dashboard, report apps, report ad-units, report bidders, and report breakdown accept --timezone. Use an IANA name such as America/New_York or Asia/Shanghai. Omitting the flag preserves UTC periods, buckets, and output. This is a reporting command flag, not a global root flag.

cloudx report dashboard --period 2026-03-08 --timezone America/New_York

This selects the 23-hour local day from 2026-03-08T05:00:00Z through 2026-03-09T03:59:59Z. A local day may contain 23 or 25 hours during daylight-saving transitions. last_7d and last_30d still select rolling 168-hour and 720-hour windows.

The CLI converts calendar boundaries into Unix timestamps once. For direct API requests, timezone controls calendar grouping; start_time and end_time remain absolute Unix timestamps and are not shifted. Dashboard date and day/week/month breakdown labels follow the selected timezone. Dashboard bucket_start and hourly breakdown keys remain UTC RFC 3339 instants, keeping repeated local hours distinct.

SDK reports, hourly dashboard/breakdown reports, and breakdowns grouped by bidder require whole-hour timezone offsets throughout the requested period. Fractional-offset zones such as Asia/Kolkata return an error for those reports. report ab-test accepts --timezone UTC and rejects non-UTC zones. Invalid timezone names also return errors.

Existing range limits still apply: the start instant must be on or after 2020-01-01T00:00:00Z, and aggregate reporting windows cannot exceed 744 hours. A 31-date range spanning a fall daylight-saving transition can exceed that limit.

report export, activity exports, and auction inspection retain their UTC behavior and do not accept this flag. Demand Comparison retains its separate completed reporting window rules.

Granularity Values

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

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.

report export always uses UTC buckets.

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.

Source names are case-insensitive and normalized by the CLI. External source values name the mediation platform that forwarded the ILRD, not the downstream demand network and not a CloudX bidder. For example, AppLovin MAX rows with ADMOB_BIDDING demand are reported under applovin, not admob.

admob means AdMob Mediation ILRD forwarded by the publisher’s app. It is not CloudX’s AdMob estimated demand, so admob rows keep reporting impressions and revenue after AdMob estimated is paused in the CloudX dashboard.

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 hour (UTC unless --timezone is supplied):

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.

You can request up to four dimensions. The bidder dimension is available for reporting periods beginning on or after June 1, 2026.

Metrics

Use a comma-separated list with --metrics.

Rate metrics are computed from summed components for each returned row. They are not averaged from precomputed rates. With --json, the response has dimensions, metrics, rows, and row_count. Each row has a string dimensions map and a number metrics map. Both maps contain only the names you requested. CloudX returns at most 100,000 rows.

Options

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

Bidder delivery and click performance by app, format, and ad unit:

cloudx report breakdown --by bidder,app,format,ad_unit --metrics requests,bid_requests,fills,impressions,clicks,ctr

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 demand-comparison

Compares CloudX-recognized revenue, eCPM, and impressions with daily reports from supported demand partners.

The command requires the reports:read permission and Demand Comparison access. The API returns 403 Forbidden when the account does not have feature access.

Usage

cloudx report demand-comparison [flags]

Completed reporting window

If you omit --period, the command selects the latest 30 completed calendar dates:

• At or after 12:00 UTC, the range ends yesterday.
• Before 12:00 UTC, the range ends the day before yesterday.

Explicit periods accept YYYY-MM-DD or YYYY-MM-DD..YYYY-MM-DD. The CLI converts those calendar dates through the IANA timezone in --timezone, which defaults to UTC. Starting with CLI 0.41, you can request any length of completed calendar-date window within available history. CLI 0.40 and earlier limit explicit windows to 31 calendar dates, inclusive. Some selected dates may have no CloudX or partner data.

The range must meet these rules:

• The start date must be 2020-01-01 or later.
• The end date must not precede the start date.
• The end date must be complete under the 12:00 UTC cutoff.

Named periods such as today, yesterday, and last_30d are not accepted by Demand Comparison commands.

Flags

Repeat any demand-source or ID filter, or combine values with commas:

cloudx report demand-comparison \
  --demand-source meta,moloco \
  --provider-business-id business-1 \
  --provider-business-id business-2,business-3

The CLI trims surrounding whitespace and preserves ID case. Blank or duplicate values cause an error. Omit --demand-source from the summary command to include all supported sources.

Provider business IDs, provider property IDs, and CloudX ad-unit IDs are live identifiers. They are not fixed enums. The summary and ad-unit results roll up the full requested date window. They do not expose day, country, platform, mediator, or raw partner-report rows. Partner metrics that are unavailable are omitted from JSON. They are not returned as zero.

The human-readable summary includes:

• CloudX, partner, and delta values for revenue, eCPM, and impressions
• Matched and total CloudX ad-unit counts
• has_mapping_gaps, shown as MAPPING GAPS
• The latest partner report date and the number of partner report dates

has_mapping_gaps covers missing or ambiguous mappings on either side. A CloudX-only gap remains a summary warning. It does not become a partner row in the ad-unit report.

cloudx report demand-comparison --demand-source meta,moloco

cloudx report demand-comparison-ad-units

Returns partner ad-unit aggregates for exactly one demand source.

Usage

cloudx report demand-comparison-ad-units --demand-source DEMAND_SOURCE [flags]

The default --view mapped output includes partner identity, associated CloudX ad-unit IDs, and CloudX-versus-partner revenue, eCPM, and impression metrics.

Use --view unmapped to return partner rows with no current CloudX mapping or ambiguous attribution:

cloudx report demand-comparison-ad-units \
  --demand-source moloco \
  --view unmapped

Unmapped rows have status: unmapped. Their excluded_partner_revenue and excluded_partner_impressions values quantify partner activity excluded from the mapped comparison. The human-readable table does not show zero-valued CloudX comparison columns for this view.

The API applies --cloudx-ad-unit-id after it forms each partner-ad-unit aggregate. If any associated CloudX ID matches, the response keeps the aggregate’s full totals and complete cloudx_ad_unit_ids list.

The response uses these pagination fields:

Human-readable output prints a warning when truncated is true. Use more specific provider or ad-unit filters to narrow the result.

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

Daily exports return 14 columns in this order:

date,network_name,app_name,app_store_id,platform,ad_unit_id,ad_type,network_placement,country,impressions,clicks,revenue,attempts,responses
2026-03-29,meta,Sample Puzzle,com.example.puzzle,iOS,ad-unit-home,banner,home-banner,US,1200,18,14.25,1500,960

date is a UTC calendar date. country is ISO alpha-2. app_store_id is the configured app bundle, not always a numeric store ID. network_name, app IDs, ad-unit IDs, and placement IDs are dynamic values. This command returns production data only. device_os accepts only iOS or Android as a filter. It does not normalize the returned platform text.

Legacy reporting uses SSP requests for attempts and returns 0 for responses. SDK reporting uses ad requests for attempts and fills for responses.

Hourly exports replace only the first column with bucket_start, an RFC 3339 UTC timestamp:

bucket_start,network_name,app_name,app_store_id,platform,ad_unit_id,ad_type,network_placement,country,impressions,clicks,revenue,attempts,responses
2026-03-29T13:00:00Z,meta,Sample Puzzle,com.example.puzzle,iOS,ad-unit-home,banner,home-banner,US,120,2,1.43,150,96

JSON Output

With --json, rows is an array of string arrays. Each row position matches columns; row_count is the number of returned rows.

Related

• CloudX CLI Overview
• Installation
• Authentication Commands
• Activity Exports
• Examples