> ## 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.
# Tool Reference
> Reference for every public CloudX MCP tool, including parameters, supported filters, and response fields.
# Tool Reference
CloudX MCP currently exposes 17 public tools: seven reporting tools, four auction-inspection tools, five configuration tools, and one documentation search tool. The authenticated user is always scoped to their CloudX account.
## Tool Summary
| Tool | Purpose | Extra Filters | Main Response Fields |
| -------------------- | ----------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------- |
| `GetReportDashboard` | Summary KPIs plus chart data | `test_mode`, `country`, `device_os` | `summary`, `chart_data` |
| `GetReportBreakdown` | Custom grouped report rows | `by`, `metrics`, ranking and metric filters | `dimensions`, `metrics`, `rows`, `row_count` |
| `GetReportBidders` | Bidder-level performance | `test_mode`, `country`, `device_os` | `bidders` |
| `GetReportApps` | App-level performance | `test_mode`, `country`, `device_os` | `apps` |
| `GetReportAdUnits` | Ad unit-level performance | `test_mode`, `country`, `device_os`, `app_bundle`, `ad_unit_type` | `ad_units` |
| `GetReportExport` | Raw export rows in JSON shape | `country`, `device_os` | `columns`, `rows`, `row_count` |
| `GetReportABTest` | Control and test-variant performance | `ab_test_id` | `control`, `test`, statistical fields |
| `GetAuctionList` | Recent auctions matching filters | app, ad unit, traffic, ILRD, and mediator filters | `auctions` |
| `GetAuctionShow` | One auction with optional related details | `with` | `auctions`, `rounds`, `bids`, `ilrd`, `external_ilrd` |
| `GetAuctionRounds` | Auction rounds or aggregate round metrics | `auction_id`, `metric`, traffic filters | `rounds`, `metrics` |
| `GetAuctionBids` | Bid and non-bid rows | traffic filters, `floor_source` | `bids` |
| `GetConfigShow` | Live, published, or draft configuration | `id`, `version`, `draft` | config metadata, `data`, `yaml` |
| `GetConfigValidate` | Server-side config validation | `id`, `version` | `valid`, `issues`, counts, `source` |
| `GetConfigHistory` | Recent config history | `since`, `author`, `include_drafts`, `limit` | `entries` |
| `PostConfigEdit` | Typed inventory configuration edits | `body.config_id`, `body.operations`, `body.summary` | draft or published config result |
| `PostConfigPublish` | Validate and publish a draft | `body.draft_id`, `body.version_label` | `config_id`, `version_number`, `validation` |
| `SearchDocs` | CloudX documentation search | none | `results` |
Read-only tools require the corresponding `reports:read`, `auctions:read`, or `configuration:read` permission. `PostConfigEdit` and `PostConfigPublish` require `configuration:write`.
## Reporting Tool Parameters
| Parameter | Required | Supported By | Notes |
| -------------- | -------- | ----------------------------------------------------- | --------------------------------------------------------- |
| `start_time` | Yes | Reporting tools | Unix timestamp in seconds, UTC |
| `end_time` | Yes | Reporting tools | Unix timestamp in seconds, UTC |
| `country` | No | Dashboard, Breakdown, Bidders, Apps, Ad Units, Export | ISO-2 country code |
| `device_os` | No | Dashboard, Breakdown, Bidders, Apps, Ad Units, Export | `iOS` or `Android` |
| `test_mode` | No | Dashboard, Breakdown, Bidders, Apps, Ad Units | `production`, `test`, or `all` |
| `app_bundle` | No | Ad Units only | Bundle ID such as `com.example.game` |
| `ad_unit_type` | No | Ad Units only | `BANNER`, `INTERSTITIAL`, `REWARDED`, `MREC`, or `NATIVE` |
## `GetReportDashboard`
Use this tool for top-line reporting across a time range.
### Best For
* total revenue and fill rate checks
* daily trend analysis
* quick health checks by country or platform
### Parameters
| Parameter | Type | Required |
| ------------ | ------- | -------- |
| `start_time` | integer | Yes |
| `end_time` | integer | Yes |
| `country` | string | No |
| `device_os` | string | No |
| `test_mode` | string | No |
### Response Shape
* `summary`
* `chart_data`
`summary` includes fields such as `total_requests`, `total_impressions`, `revenue`, `fill_rate`, `ecpm`, `total_clicks`, `ctr`, and `total_users`.
## `GetReportBreakdown`
Use this tool to choose the grouping dimensions and metrics for a report instead of using a fixed dashboard shape.
### Parameters
| Parameter | Type | Required | Notes |
| ------------- | ------- | -------- | -------------------------------------------------------------------------------------------- |
| `start_time` | integer | Yes | Unix seconds; range cannot exceed 31 days |
| `end_time` | integer | Yes | Unix seconds; range cannot exceed 31 days |
| `by` | string | Yes | Comma-separated: `hour`, `day`, `week`, `month`, `country`, `os`, `app`, `ad_unit`, `format` |
| `metrics` | string | Yes | Comma-separated metric names |
| `country` | string | No | ISO-2 country code |
| `device_os` | string | No | `iOS` or `Android` |
| `test_mode` | string | No | Defaults to `production` |
| `granularity` | string | No | `daily` or `hourly`; defaults to `daily` |
| `top` | integer | No | Top 1–1000 rows by the first metric |
| `bottom` | integer | No | Bottom 1–1000 rows by the first metric |
| `having` | string | No | Metric expression such as `revenue > 10` |
### Response Shape
* `dimensions`: requested dimension names
* `metrics`: requested metric names
* `rows`: objects containing `dimensions` and `metrics` maps
* `row_count`
## `GetReportBidders`
Use this tool when you want to compare demand partners.
### Best For
* finding the highest-revenue bidder
* checking bid rate and win rate by partner
* comparing supply quality across countries or platforms
### Parameters
| Parameter | Type | Required |
| ------------ | ------- | -------- |
| `start_time` | integer | Yes |
| `end_time` | integer | Yes |
| `country` | string | No |
| `device_os` | string | No |
| `test_mode` | string | No |
### Response Shape
* `bidders`
Each bidder row can include `name`, `requests`, `bids`, `bid_rate`, `impressions`, `win_rate`, `revenue`, and `ecpm`.
## `GetReportApps`
Use this tool to compare app-level performance within an account.
### Best For
* ranking apps by revenue
* comparing iOS and Android portfolio performance
* spotting low fill-rate apps
### Parameters
| Parameter | Type | Required |
| ------------ | ------- | -------- |
| `start_time` | integer | Yes |
| `end_time` | integer | Yes |
| `country` | string | No |
| `device_os` | string | No |
| `test_mode` | string | No |
### Response Shape
* `apps`
Each app row can include `app_id`, `name`, `platform`, `impressions`, `fill_rate`, `revenue`, and `ecpm`.
## `GetReportAdUnits`
Use this tool for placement-level investigation.
### Best For
* comparing banners vs rewarded vs interstitial
* isolating a single app bundle
* finding weak or high-value ad placements
### Parameters
| Parameter | Type | Required |
| -------------- | ------- | -------- |
| `start_time` | integer | Yes |
| `end_time` | integer | Yes |
| `country` | string | No |
| `device_os` | string | No |
| `test_mode` | string | No |
| `app_bundle` | string | No |
| `ad_unit_type` | string | No |
### Response Shape
* `ad_units`
Each row can include `ad_unit_id`, `name`, `app_name`, `app_bundle`, `type`, `impressions`, `fill_rate`, `revenue`, and `ecpm`.
## `GetReportExport`
Use this tool when you need tabular data rather than a summarized report.
### Best For
* passing data into spreadsheets
* validating downstream analytics
* handing structured rows to another tool or agent
### Parameters
| Parameter | Type | Required |
| ------------ | ------- | -------- |
| `start_time` | integer | Yes |
| `end_time` | integer | Yes |
| `country` | string | No |
| `device_os` | string | No |
### Response Shape
* `columns`
* `rows`
* `row_count`
## `GetReportABTest`
Use this tool to compare an A/B test's control and test variants over a time range.
### Parameters
| Parameter | Type | Required |
| ------------ | ------- | -------- |
| `ab_test_id` | string | Yes |
| `start_time` | integer | Yes |
| `end_time` | integer | Yes |
The requested range cannot exceed 31 days.
### Response Shape
* `control` and `test`, each with `cumulative` metrics and daily rows
* statistical fields when available: `lift`, `p_value`, `chi_squared_p`, `ci_low`, `ci_high`, `n_control`, `n_test`, and `required_n`
* `status`, such as `in_progress`, `directional`, `achieved`, or `invalidated`
## Auction Inspection Tools
Auction time-range tools accept Unix timestamps in seconds and a maximum range of 31 days. Their common optional filters are `test_mode`, `app_bundle`, `ad_unit_id`, `country`, and `device_os`. Row limits default to 50 and accept values from 1 to 500.
## `GetAuctionList`
Use this tool to find recent auctions before drilling into one auction.
### Parameters
| Parameter | Type | Required | Notes |
| ------------------- | ------- | -------- | ---------------------------------------------- |
| `start_time` | integer | Yes | Unix seconds |
| `end_time` | integer | Yes | Unix seconds |
| `test_mode` | string | No | `production`, `test`, or `all` |
| `app_bundle` | string | No | App bundle identifier |
| `ad_unit_id` | string | No | Ad unit ID |
| `country` | string | No | ISO-2 country code |
| `device_os` | string | No | `iOS` or `Android` |
| `has_ilrd` | boolean | No | Require CloudX impression-level revenue data |
| `has_external_ilrd` | boolean | No | Require external impression-level revenue data |
| `mediator` | string | No | `applovin`, `admob`, or `levelplay` |
| `limit` | integer | No | 1–500; defaults to 50 |
`has_ilrd` and `has_external_ilrd` are mutually exclusive. `mediator` can only be used with `has_external_ilrd: true`.
The response contains an `auctions` array with IDs, timestamps, app and ad-unit context, winner details, bid counts, duration, A/B test context, and ILRD availability.
## `GetAuctionShow`
Use this tool after `GetAuctionList` when you know the auction ID.
### Parameters
| Parameter | Type | Required | Notes |
| ------------ | ------ | -------- | ---------------------------------------------------------- |
| `auction_id` | string | Yes | CloudX auction ID |
| `with` | string | No | Comma-separated: `rounds`, `bids`, `ilrd`, `external-ilrd` |
The response includes `auction_id` and `auctions`. Requested related data appears in `rounds`, `bids`, `ilrd`, and `external_ilrd`.
## `GetAuctionRounds`
Use this tool either to inspect rounds for one `auction_id` or to aggregate round behavior over a time range.
### Parameters
| Parameter | Type | Required | Notes |
| ------------ | ------- | ----------- | --------------------------------------------------------------------------------------- |
| `auction_id` | string | Conditional | Use for one auction |
| `start_time` | integer | Conditional | Use with `end_time` for aggregate analysis |
| `end_time` | integer | Conditional | Use with `start_time` for aggregate analysis |
| `metric` | string | No | `distribution`, `duration`, `cleared-on`, or `skip-reason` when `auction_id` is omitted |
| `test_mode` | string | No | `production`, `test`, or `all` |
| `app_bundle` | string | No | App bundle identifier |
| `ad_unit_id` | string | No | Ad unit ID |
| `country` | string | No | ISO-2 country code |
| `device_os` | string | No | `iOS` or `Android` |
| `limit` | integer | No | 1–500; defaults to 50 |
The response contains detailed `rounds`, aggregate `metrics`, or both.
## `GetAuctionBids`
Use this tool to inspect bid and non-bid rows across a time range.
### Parameters
| Parameter | Type | Required | Notes |
| -------------- | ------- | -------- | ------------------------------------------------- |
| `start_time` | integer | Yes | Unix seconds |
| `end_time` | integer | Yes | Unix seconds |
| `test_mode` | string | No | `production`, `test`, or `all` |
| `app_bundle` | string | No | App bundle identifier |
| `ad_unit_id` | string | No | Ad unit ID |
| `country` | string | No | ISO-2 country code |
| `device_os` | string | No | `iOS` or `Android` |
| `floor_source` | string | No | `static`, `dynamic`, `publisher`, or `configured` |
| `limit` | integer | No | 1–500; defaults to 50 |
The `bids` response array includes bidder, status, price, winner, latency, floor, rejection, and auction context.
## Configuration Tools
`PostConfigEdit` and `PostConfigPublish` change account configuration. Review the returned draft and validation result before publishing.
## `GetConfigShow`
Fetch the live config by omitting all parameters, or select a draft or published version.
| Parameter | Type | Required | Notes |
| --------- | ------- | -------- | ----------------------------------------------------------- |
| `id` | string | No | Published or draft config row ID |
| `version` | integer | No | Published version number |
| `draft` | boolean | No | Return the account draft; use `id` if multiple drafts exist |
The response includes `id`, `kind`, version and author metadata, parsed `data`, and `yaml`.
## `GetConfigValidate`
Validate the live config by omitting all parameters, or select a config with `id` or `version`.
| Parameter | Type | Required |
| --------- | ------- | -------- |
| `id` | string | No |
| `version` | integer | No |
The response includes `valid`, `error_count`, `warning_count`, `issues`, `source`, and `yaml`. Each issue can include its severity, code, message, path, line, and column.
## `GetConfigHistory`
List recent configuration rows, newest first. This returns at most 200 rows and is not an exhaustive account history.
| Parameter | Type | Required | Notes |
| ---------------- | ------- | -------- | ----------------------------------- |
| `since` | string | No | RFC3339 timestamp or `YYYY-MM-DD` |
| `author` | string | No | User ID, email, or name substring |
| `include_drafts` | boolean | No | Defaults to published versions only |
| `limit` | integer | No | 1–200; defaults to 50 |
Each `entries` row includes the config ID, kind, version, author, creation time, description, and publish-time diff counts.
## `PostConfigEdit`
Apply typed changes to apps, ad units, ad unit groups, account bidders, network mappings, lists, tags, test devices, line items, or A/B tests.
### Request Shape
| Parameter | Type | Required | Notes |
| ----------------- | ------ | ----------- | ----------------------------------------------------------------------------------- |
| `body.config_id` | string | No | Defaults to live; edits drafts in place and copies published configs to a new draft |
| `body.operations` | array | Yes | Each object must contain exactly one supported action |
| `body.summary` | string | Conditional | Required for ordinary draft edits; optional for A/B test operations |
Supported actions are:
* apps: `create_app`, `update_app`, `delete_app`
* ad units: `create_ad_unit`, `update_ad_unit`, `delete_ad_unit`
* network and bidder settings: `upsert_network_mapping`, `delete_network_mapping`, `upsert_account_bidder`
* ad unit groups: `create_ad_unit_group`, `update_ad_unit_group`, `delete_ad_unit_group`, `remove_ad_unit_from_group`
* lists and tags: `create_list`, `update_list`, `delete_list`, `create_tag`, `update_tag`, `delete_tag`
* test devices: `upsert_test_device`, `delete_test_device`
* A/B tests: `create_ab_test`, `update_ab_test`, `start_ab_test`, `end_ab_test`, `promote_ab_test`, `delete_ab_test`
* line items: `create_line_item`, `update_line_item`, `delete_line_item`
Ordinary edits and `create_ab_test` return a draft. The A/B test update, start, end, promote, and delete actions publish immediately and must be the only operation in the request. Ad-unit and line-item `bidfloor` values are decimal USD CPM.
## `PostConfigPublish`
Publish a draft as the live configuration. The same server-side checks used by the CloudX app run before the draft becomes live.
| Parameter | Type | Required |
| -------------------- | ------ | -------- |
| `body.draft_id` | string | Yes |
| `body.version_label` | string | No |
The response includes `config_id`, `version_number`, and `validation`. A blocking validation failure returns an MCP error and does not publish the draft.
## `SearchDocs`
Use this tool to search CloudX documentation from an MCP client before answering setup, configuration, SDK, CLI, dashboard, network, or reporting questions.
### Best For
* finding the right documentation page for a CloudX workflow
* grounding an answer in current docs before explaining a feature
* retrieving relevant setup or troubleshooting snippets without leaving the AI client
### Parameters
| Parameter | Type | Required | Notes |
| ------------ | ------ | -------- | ----------------------------- |
| `body.query` | string | Yes | Natural-language search query |
### Tool Call Shape
```json theme={null}
{
"name": "SearchDocs",
"arguments": {
"body": {
"query": "report filters"
}
}
}
```
### Response Shape
* `results`
Each result includes:
* `content`: matching documentation snippet
* `path`: documentation path such as `/en/cli/reporting`
* `url`: absolute docs URL
* `metadata`: page metadata such as title, when available
## Error Behavior
These tools return MCP error results when the request cannot be fulfilled. Common causes include:
* missing `start_time` or `end_time`
* invalid enum values such as `device_os: "ios"` instead of `iOS`
* a time range longer than 31 days
* a missing auction or config ID
* insufficient permission for the requested tool
* config edit or publish validation failures
For `SearchDocs`, a blank or missing query returns `query is required`. If documentation search is temporarily unavailable, the tool returns a docs search error.
## Related
* [Installation](/en/mcp/installation)
* [Examples](/en/mcp/examples)