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.
insights_capabilities
List supported metrics, reporting levels, breakdowns, and pagination settings. Access:mcp:read.
Arguments: none.
Full input schema
Full input schema
{
"additionalProperties": false,
"properties": {},
"type": "object"
}
insights_query
Read one page of reporting data. Callinsights_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 |
Full input schema
Full input schema
{
"$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"
}
insights_rank
Rank performance over a date range. Choose one reporting level, then useglobal 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. |
Full input schema
Full input schema
{
"$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"
}