> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudx.io/llms.txt > Use this file to discover all available pages before exploring further. # Reporting > 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 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. ```bash theme={null} 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. | | `` | 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: ```text theme={null} Period: last_30d Test mode: production Country: US Device OS: iOS Granularity: hourly ``` ### JSON Pass `--json` to return structured JSON: ```bash theme={null} cloudx report dashboard --json ``` All command examples are collected on the [Examples](/en/cli/examples) page. ## `cloudx report dashboard` Shows summary metrics and daily or hourly chart rows. ### Usage ```bash theme={null} cloudx report dashboard [--period ] [--granularity daily|hourly] [flags] ``` Use `--source all` to include external mediator ILRD in dashboard revenue, impressions, eCPM, and source breakdowns: ```bash theme={null} cloudx report dashboard --period last_7d --source all ``` Use `--granularity hourly` to show chart rows by UTC hour: ```bash theme={null} cloudx report dashboard --period 2026-04-01 --granularity hourly ``` ### Example ```bash theme={null} $ 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 ```bash theme={null} cloudx report breakdown --by --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 ` | Filter rows by a metric expression, for example `revenue > 10`. | ### Having Expressions `--having` filters rows after grouping. It supports one metric comparison: ```text theme={null} ``` 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: ```bash theme={null} --having 'revenue > 10' --having 'impressions >= 1000' --having 'ctr < 1.5' ``` Invalid examples: ```bash theme={null} --having 'revenue > 10 OR 1=1' --having 'country = US' --having 'revenue > impressions' ``` ### Examples Daily revenue, impressions, and eCPM by country: ```bash theme={null} cloudx report breakdown --period last_7d --by day,country --metrics revenue,impressions,ecpm ``` Hourly app fill rate for one day: ```bash theme={null} cloudx report breakdown --period 2026-04-01 --granularity hourly --by hour,app --metrics requests,impressions,fill_rate ``` Top ad units by revenue: ```bash theme={null} cloudx report breakdown --by app,ad_unit --metrics revenue,ecpm --top 10 ``` JSON output filtered by a metric threshold: ```bash theme={null} cloudx report breakdown --by country --metrics revenue,impressions --having 'revenue > 10' --json ``` ### Example Output ```bash theme={null} $ 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 ```bash theme={null} cloudx report bidders [--period ] [flags] ``` ### Example ```bash theme={null} $ 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 ```bash theme={null} cloudx report apps [--period ] [flags] ``` Use a comma-separated source list to compare CloudX against a mediator for each app: ```bash theme={null} cloudx report apps --period last_30d --source cloudx,applovin ``` ### Example ```bash theme={null} $ 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 ```bash theme={null} cloudx report ad-units [--period ] [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: ```bash theme={null} cloudx report ad-units --app com.example.game --source all ``` ### Example ```bash theme={null} $ 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 ```bash theme={null} cloudx report export [--period ] [--granularity daily|hourly] [flags] ``` Use `--granularity hourly` when downstream reporting needs UTC hour buckets: ```bash theme={null} cloudx report export --period 2026-04-01 --granularity hourly ``` ### Example ```bash theme={null} $ cloudx report export date,network_name,country 2026-03-29,meta,US ``` Hourly exports use `bucket_start` for the first column: ```bash theme={null} $ 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 ```bash theme={null} cloudx report impressions export --date YYYY-MM-DD [filters] [--wait] [--output ] ``` `--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: ```bash theme={null} cloudx report impressions export --date 2026-07-16 ``` Wait for completion and download the result: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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. | ## Related * [CloudX CLI Overview](/en/cli) * [Installation](/en/cli/installation) * [Authentication Commands](/en/cli/authentication) * [Examples](/en/cli/examples)