| App | TikTok Ads |
| Operation ID | tiktok_ads_get_gmv_max_report |
| Type | Action |
| Connection | tiktok_ads (required) |
| Credits per run | 1 |
| Agent / MCP tool | Yes |
Inputs
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
accounts | array (also accepts a comma-separated string) | Yes | - | A list of accounts to query. Ask the user for it if not provided, or use other tools to fetch the accounts details first. You can select multiple accounts in one go, and if you want to break down the data by account, add ‘accountName’ to fields. |
date_range | DateRange | Yes | - | Date range for the report. Options: - Use preset=‘FIXED’ with start/end dates (YYYY-MM-DD) for specific date ranges - Use preset=‘CUSTOM’ with start/end dynamic values ({{nodeId__data.start_date}}) for dates from other nodes - Use other presets (TODAY, YESTERDAY, LAST_7_DAYS, etc.) for predefined ranges When using ‘FIXED’ or ‘CUSTOM’ presets, both start and end fields are required. For other presets, start and end will be ignored and calculated automatically. |
metrics | array of string or SelectableOption | Yes | - | List of metrics to query. Don’t try to guess metric names, use the relevant tool to discover available metrics or prompt user to browse metrics in the UI. |
dimensions | array of string or SelectableOption | No | - | List of dimensions to query. Don’t try to guess dimension names, use the relevant tool to discover available dimensions or prompt user to browse dimensions in the UI. |
filters | array of FilterItem | No | - | List of filters to apply to the report. Each filter must have a field, operator, and value. Filters are combined using AND logic. If you want to use OR logic, use relevant operators like REGEXP_MATCH or IN_LIST. |
orders | array of OrderItem | No | - | List of fields to sort the report by. Each order must have a field and direction. The field must be one of the current selected metrics or dimensions. |
limit | integer | No | - | The maximum number of rows to return. |
options | ReportOptions | No | - | Additional options for the report. |
store_id | string or SelectItem | Yes | - | The TikTok Shop to report on, from tiktok_ads_list_gmv_max_stores (use a store with is_gmv_max_available true). One store per report. |
campaign_type | enum (PRODUCT, LIVE) | No | - | PRODUCT (Product GMV Max) or LIVE (LIVE GMV Max). Required for campaign, product, post, LIVE room or duration breakdowns. Omit for account-level totals across both types. |
DateRange
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
start | string | No | - | The start date of the date range to query, format: YYYY-MM-DD or dynamic node reference like {{nodeId__data.start_date}}. Required when preset is ‘FIXED’ or ‘CUSTOM’. |
end | string | No | - | The end date of the date range to query, format: YYYY-MM-DD or dynamic node reference like {{nodeId__data.end_date}}. Required when preset is ‘FIXED’ or ‘CUSTOM’. |
preset | string | No | - | Predefined date ranges or input modes: - Use ‘FIXED’ or leave empty when you want to specify exact dates (YYYY-MM-DD format) in start/end fields - Use ‘CUSTOM’ when you want to use dynamic values from other nodes ({{nodeId__data.start_date}} format) in start/end fields - Use other presets (TODAY, YESTERDAY, LAST_7_DAYS, etc.) for predefined date ranges (start/end will be ignored) LAST_N_MONTHS and LAST_N_WEEKS are complete calendar periods ending with last month or last week, so they exclude the current month or week; for a rolling window up to yesterday use LAST_N_DAYS (for example LAST_90_DAYS) or a FIXED range. When using ‘FIXED’ or ‘CUSTOM’, both start and end fields are required. |
compare | CompareOptions | No | - | Optional comparison date range settings. ALWAYS use this field for comparisons; DO NOT create additional requests or nodes, as the backend returns current, comparison, and delta metrics in a single call. If one period has no data at all, only the period with data is returned and no delta row; treat the missing period as zero. |
FilterItem
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
field | string or SelectableOption | Yes | - | The field to filter on, must be one of the current selected metrics or dimensions. |
operator | string | Yes | - | The operator to use for filtering. Must be one of the supported values. Use REGEXP_MATCH to search/filter by multiple OR values like ’.(summer|holiday).’ |
value | string | Yes | - | The value to filter by, always as a string: text, a number, or a regex. For IN_LIST and NOT_IN_LIST, pass the values as one comma-separated string such as ‘a,b,c’, not as an array. For regex values, escape backslashes once in the JSON string: write \b for a word boundary, not \b. |
OrderItem
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
field | string or SelectableOption | Yes | - | The field to sort by. must be one of the current selected metrics or dimensions. |
direction | string | Yes | - | The order to sort by, must be one of ‘ASC’, ‘DESC’ |
ReportOptions
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
pretty_column_names | boolean | No | - | whether to use pretty column names in the report (e.g., ‘Clicks’ instead of ‘clicks’). |
show_percent_sign | boolean | No | - | whether to show percent sign for percentage metrics (e.g., ‘58%’ instead of ‘0.58’). |
currency_symbol | string | No | - | the currency symbol to use for monetary values (e.g., ’$’). |
compact_numbers | boolean | No | - | whether to use compact number format (e.g., ‘1K’) and round decimals. Takes priority over thousand_separators. |
thousand_separators | boolean | No | - | whether to format numbers with thousand separators (e.g., ‘105,878’) and round decimals. Ignored if compact_numbers is enabled. |
pivot_dimensions | array of string | No | - | the dimensions to pivot the report on. Must be one of the current selected dimensions. |
include_zero_impressions | boolean | No | - | whether to include zero impressions in the report. |
SelectItem
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
value | string | Yes | - | The value of the selectable item. |
label | string | Yes | - | The label of the selectable item, used for display purposes. If not provided, defaults to the value. |
SelectableOption
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
value | string | Yes | - | |
label | string | Yes | - |
CompareOptions
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
start | string | No | - | The start date of the comparison range, format: YYYY-MM-DD. Optional if preset is provided. |
end | string | No | - | The end date of the comparison range, format: YYYY-MM-DD. Optional if preset is provided. |
preset | string | No | - | Predefined comparison ranges. When provided, start and end will be ignored. |
comparison_format | string | No | rows | Comparison output layout: ‘rows’ returns separate rows for current, comparison, and delta along with date ranges; ‘columns’ returns a single row with delta values only as additional *_pct or *_change columns depending on comparison_value_type. |
comparison_value_type | string | No | percentage | Value type: ‘percentage’ or ‘absolute’ |
Output
Type:List[Dict]
Returns one row per combination of the selected dimensions with the selected metrics, like other get_report nodes. ROI, cost per order, product click rate and cost per LIVE view are calculated from their totals.
Fields: dynamic (depend on the inputs)