> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superlaunch.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Insights tools

> Query reports and rank advertising performance.

Call `insights_capabilities` before querying. Choose the reporting period, entity level, metrics, conversion event, and attribution window. Follow query cursors before reporting complete results.

The tables list arguments and common nested fields. Expand **Full input schema** for all fields and allowed values. Workspace and account permissions apply to every tool.

<span id="insights-capabilities" />

## insights\_capabilities

List supported metrics, reporting levels, breakdowns, and pagination settings.

**Access:** `mcp:read`.

**Arguments:** none.

<Accordion title="Full input schema">
  ```json theme={null}
  {
    "additionalProperties": false,
    "properties": {},
    "type": "object"
  }
  ```
</Accordion>

<span id="insights-query" />

## insights\_query

Read one page of reporting data. Call `insights_capabilities` to check supported combinations.

Pages default to 25 rows, with a maximum of 100. Follow `next_cursor` with the same filters to read more. Use sorting and `min_spend` to narrow results, or `entity_ids` to inspect specific objects.

For structured metrics such as `actions` and `action_values`, supply both `action_types` and `attribution_windows`. For example, use `action_types: ["omni_purchase"]` and `attribution_windows: ["7d_click"]` for purchases attributed within seven days of a click. Choose these values to match the report you need.

Daily account, campaign, and ad-set totals can aggregate compatible metrics from ad rows. Reach and frequency use the requested reporting level.

**Access:** `mcp:read`.

| Parameter | Type | Required / default | Details |
| - | - | - | - |
| `ad_account_ids` | array of uuid | Required | minItems: `1`. maxItems: `20`. |
| `date_from` | string | Required | First reporting date in `YYYY-MM-DD` format. |
| `date_to` | string | Required | Last reporting date in `YYYY-MM-DD` format. |
| `metrics` | array of strings | Required | minItems: `1`. maxItems: `20`. Allowed values are in the full input schema. |
| `entity_level` | account, campaign, adset, ad | `"ad"` | Reporting level: account, campaign, ad set, or ad. |
| `entity_ids` | array of string or null | `null` | |
| `report_spec` | base\_daily, demographic\_daily, country\_daily | `"base_daily"` | Report format from `insights_capabilities`. |
| `grain` | daily, period | `"daily"` | Time grouping from `insights_capabilities`. |
| `action_types` | array of string or null | `null` | Conversion events to include in structured metrics. |
| `attribution_windows` | array of value, 1d\_click, 7d\_click, 1d\_view or null | `null` | Attribution windows to include in structured metrics. |
| `min_spend` | number or null | `null` | Minimum spend in account-currency major units. |
| `sort_by` | entity\_id, date, spend, impressions, clicks, ctr, purchases, roas | `"entity_id"` | |
| `sort_direction` | asc, desc | `"asc"` | |
| `sort_action_type` | string | `"omni_purchase"` | |
| `sort_attribution` | value, 1d\_click, 7d\_click, 1d\_view | `"value"` | |
| `limit` | integer | `25` | minimum: `1`. maximum: `100`. |
| `cursor` | string or null | `null` | |

<Accordion title="Full input schema">
  ```json theme={null}
  {
    "$defs": {
      "InsightAccountIds": {
        "items": {
          "format": "uuid",
          "type": "string"
        },
        "maxItems": 20,
        "minItems": 1,
        "type": "array"
      },
      "InsightActionType": {
        "maxLength": 200,
        "minLength": 1,
        "type": "string"
      },
      "InsightActionTypes": {
        "items": {
          "$ref": "#/$defs/InsightActionType"
        },
        "maxItems": 50,
        "type": "array"
      },
      "InsightAttributionWindow": {
        "enum": [
          "value",
          "1d_click",
          "7d_click",
          "1d_view"
        ],
        "type": "string"
      },
      "InsightAttributionWindows": {
        "items": {
          "$ref": "#/$defs/InsightAttributionWindow"
        },
        "maxItems": 4,
        "type": "array"
      },
      "InsightEntityId": {
        "maxLength": 300,
        "minLength": 1,
        "type": "string"
      },
      "InsightEntityIds": {
        "items": {
          "$ref": "#/$defs/InsightEntityId"
        },
        "maxItems": 100,
        "type": "array"
      },
      "InsightEntityLevel": {
        "enum": [
          "account",
          "campaign",
          "adset",
          "ad"
        ],
        "type": "string"
      },
      "InsightGrain": {
        "enum": [
          "daily",
          "period"
        ],
        "type": "string"
      },
      "InsightLimit": {
        "maximum": 100,
        "minimum": 1,
        "type": "integer"
      },
      "InsightMetric": {
        "enum": [
          "spend",
          "impressions",
          "clicks",
          "reach",
          "frequency",
          "inline_link_clicks",
          "inline_post_engagement",
          "unique_clicks",
          "unique_inline_link_clicks",
          "quality_ranking",
          "engagement_rate_ranking",
          "conversion_rate_ranking",
          "actions",
          "action_values",
          "conversions",
          "conversion_values",
          "outbound_clicks",
          "unique_outbound_clicks",
          "video_play_actions",
          "video_continuous_2_sec_watched_actions",
          "video_15_sec_watched_actions",
          "video_30_sec_watched_actions",
          "video_p25_watched_actions",
          "video_p50_watched_actions",
          "video_p75_watched_actions",
          "video_p95_watched_actions",
          "video_p100_watched_actions",
          "video_thruplay_watched_actions",
          "video_avg_time_watched_actions",
          "video_time_watched_actions",
          "ctr",
          "cpc",
          "cpm"
        ],
        "type": "string"
      },
      "InsightMetrics": {
        "items": {
          "$ref": "#/$defs/InsightMetric"
        },
        "maxItems": 20,
        "minItems": 1,
        "type": "array"
      },
      "InsightMinimumSpend": {
        "minimum": 0,
        "type": "number"
      },
      "InsightReportSpec": {
        "enum": [
          "base_daily",
          "demographic_daily",
          "country_daily"
        ],
        "type": "string"
      },
      "InsightSortBy": {
        "enum": [
          "entity_id",
          "date",
          "spend",
          "impressions",
          "clicks",
          "ctr",
          "purchases",
          "roas"
        ],
        "type": "string"
      },
      "InsightSortDirection": {
        "enum": [
          "asc",
          "desc"
        ],
        "type": "string"
      }
    },
    "additionalProperties": false,
    "properties": {
      "ad_account_ids": {
        "$ref": "#/$defs/InsightAccountIds"
      },
      "date_from": {
        "type": "string"
      },
      "date_to": {
        "type": "string"
      },
      "metrics": {
        "$ref": "#/$defs/InsightMetrics"
      },
      "entity_level": {
        "$ref": "#/$defs/InsightEntityLevel",
        "default": "ad"
      },
      "entity_ids": {
        "anyOf": [
          {
            "$ref": "#/$defs/InsightEntityIds"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "type": [
          "array",
          "null"
        ]
      },
      "report_spec": {
        "$ref": "#/$defs/InsightReportSpec",
        "default": "base_daily"
      },
      "grain": {
        "$ref": "#/$defs/InsightGrain",
        "default": "daily"
      },
      "action_types": {
        "anyOf": [
          {
            "$ref": "#/$defs/InsightActionTypes"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "type": [
          "array",
          "null"
        ]
      },
      "attribution_windows": {
        "anyOf": [
          {
            "$ref": "#/$defs/InsightAttributionWindows"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "type": [
          "array",
          "null"
        ]
      },
      "min_spend": {
        "anyOf": [
          {
            "$ref": "#/$defs/InsightMinimumSpend"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "type": [
          "number",
          "null"
        ]
      },
      "sort_by": {
        "$ref": "#/$defs/InsightSortBy",
        "default": "entity_id"
      },
      "sort_direction": {
        "$ref": "#/$defs/InsightSortDirection",
        "default": "asc"
      },
      "sort_action_type": {
        "default": "omni_purchase",
        "type": "string"
      },
      "sort_attribution": {
        "$ref": "#/$defs/InsightAttributionWindow",
        "default": "value"
      },
      "limit": {
        "$ref": "#/$defs/InsightLimit",
        "default": 25
      },
      "cursor": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "type": [
          "string",
          "null"
        ]
      }
    },
    "required": [
      "ad_account_ids",
      "date_from",
      "date_to",
      "metrics"
    ],
    "type": "object"
  }
  ```
</Accordion>

<span id="insights-rank" />

## insights\_rank

Rank performance over a date range. Choose one reporting level, then use `global` for a combined ranking across accounts or `per_account` for separate rankings.

Conversion metrics require an explicit event and attribution window. Set minimum spend or conversion filters to exclude low-data results. `highest` and `lowest` refer to numeric values; lower CPA can be better. This tool returns compact rankings without pagination.

**Access:** `mcp:read`.

| Parameter | Type | Required / default | Details |
| - | - | - | - |
| `ad_account_ids` | array of uuid | Required | minItems: `1`. maxItems: `20`. |
| `date_from` | string | Required | First reporting date in `YYYY-MM-DD` format. |
| `date_to` | string | Required | Last reporting date in `YYYY-MM-DD` format. |
| `entity_level` | campaign, adset, ad | Required | Reporting level: account, campaign, ad set, or ad. |
| `rank_by` | spend, impressions, clicks, ctr, cpc, cpm, conversions, conversion\_value, cpa, roas | Required | Metric to rank by. |
| `action_type` | string | `"omni_purchase"` | minLength: `1`. maxLength: `200`. |
| `attribution_window` | value, 1d\_click, 7d\_click, 1d\_view | `"value"` | |
| `direction` | highest, lowest, both | `"both"` | Return highest values, lowest values, or both. |
| `rank_scope` | global, per\_account | `"global"` | Combined ranking (`global`) or one ranking per account (`per_account`). |
| `statuses` | array of string or null | `null` | |
| `min_spend` | number or null | `null` | Minimum spend in account-currency major units. |
| `min_impressions` | integer or null | `null` | |
| `min_clicks` | integer or null | `null` | |
| `min_conversions` | number or string or null | `null` | |
| `limit` | integer | `5` | minimum: `1`. maximum: `20`. |

<Accordion title="Full input schema">
  ```json theme={null}
  {
    "$defs": {
      "InsightAccountIds": {
        "items": {
          "format": "uuid",
          "type": "string"
        },
        "maxItems": 20,
        "minItems": 1,
        "type": "array"
      },
      "InsightActionType": {
        "maxLength": 200,
        "minLength": 1,
        "type": "string"
      },
      "InsightAttributionWindow": {
        "enum": [
          "value",
          "1d_click",
          "7d_click",
          "1d_view"
        ],
        "type": "string"
      },
      "InsightMinimumConversions": {
        "anyOf": [
          {
            "minimum": 0.0,
            "type": "number"
          },
          {
            "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
            "type": "string"
          }
        ]
      },
      "InsightMinimumCount": {
        "minimum": 0,
        "type": "integer"
      },
      "InsightMinimumSpend": {
        "minimum": 0,
        "type": "number"
      },
      "InsightRankDirection": {
        "enum": [
          "highest",
          "lowest",
          "both"
        ],
        "type": "string"
      },
      "InsightRankEntityLevel": {
        "enum": [
          "campaign",
          "adset",
          "ad"
        ],
        "type": "string"
      },
      "InsightRankLimit": {
        "maximum": 20,
        "minimum": 1,
        "type": "integer"
      },
      "InsightRankMetric": {
        "enum": [
          "spend",
          "impressions",
          "clicks",
          "ctr",
          "cpc",
          "cpm",
          "conversions",
          "conversion_value",
          "cpa",
          "roas"
        ],
        "type": "string"
      },
      "InsightRankScope": {
        "enum": [
          "global",
          "per_account"
        ],
        "type": "string"
      },
      "InsightStatuses": {
        "items": {
          "maxLength": 64,
          "minLength": 1,
          "type": "string"
        },
        "maxItems": 16,
        "type": "array"
      }
    },
    "additionalProperties": false,
    "properties": {
      "ad_account_ids": {
        "$ref": "#/$defs/InsightAccountIds"
      },
      "date_from": {
        "type": "string"
      },
      "date_to": {
        "type": "string"
      },
      "entity_level": {
        "$ref": "#/$defs/InsightRankEntityLevel"
      },
      "rank_by": {
        "$ref": "#/$defs/InsightRankMetric"
      },
      "action_type": {
        "$ref": "#/$defs/InsightActionType",
        "default": "omni_purchase"
      },
      "attribution_window": {
        "$ref": "#/$defs/InsightAttributionWindow",
        "default": "value"
      },
      "direction": {
        "$ref": "#/$defs/InsightRankDirection",
        "default": "both"
      },
      "rank_scope": {
        "$ref": "#/$defs/InsightRankScope",
        "default": "global"
      },
      "statuses": {
        "anyOf": [
          {
            "$ref": "#/$defs/InsightStatuses"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "type": [
          "array",
          "null"
        ]
      },
      "min_spend": {
        "anyOf": [
          {
            "$ref": "#/$defs/InsightMinimumSpend"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "type": [
          "number",
          "null"
        ]
      },
      "min_impressions": {
        "anyOf": [
          {
            "$ref": "#/$defs/InsightMinimumCount"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "type": [
          "integer",
          "null"
        ]
      },
      "min_clicks": {
        "anyOf": [
          {
            "$ref": "#/$defs/InsightMinimumCount"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "type": [
          "integer",
          "null"
        ]
      },
      "min_conversions": {
        "anyOf": [
          {
            "$ref": "#/$defs/InsightMinimumConversions"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "type": [
          "number",
          "string",
          "null"
        ]
      },
      "limit": {
        "$ref": "#/$defs/InsightRankLimit",
        "default": 5
      }
    },
    "required": [
      "ad_account_ids",
      "date_from",
      "date_to",
      "entity_level",
      "rank_by"
    ],
    "type": "object"
  }
  ```
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.