list_insights
Fetch performance insights for Meta Ads accounts, campaigns, ad sets, or ads to analyze metrics and optimize advertising strategies.
Instructions
Fetch insights for an account, campaign, ad set, or ad.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| object_id | Yes | ||
| meta_access_token | No | ||
| date_range | No | maximum | |
| breakdown | No | ||
| breakdowns | No | ||
| action_breakdowns | No | ||
| summary_action_breakdowns | No | ||
| level | No | ad | |
| page_size | No | ||
| page_cursor | No | ||
| action_attribution_windows | No | ||
| compact | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- The list_insights function serves as the primary handler for fetching insights from Meta Ads. It validates parameters, normalizes time and breakdown inputs, performs the API request, and formats the response.
async def list_insights( object_id: str, meta_access_token: Optional[str] = None, date_range: Union[str, Dict[str, str]] = "maximum", breakdown: str = "", breakdowns: Optional[List[str]] = None, action_breakdowns: Optional[List[str]] = None, summary_action_breakdowns: Optional[List[str]] = None, level: str = "ad", page_size: int = 25, page_cursor: str = "", action_attribution_windows: Optional[List[str]] = None, compact: bool = False, ) -> str: """Fetch insights for an account, campaign, ad set, or ad.""" if not str(object_id or "").strip(): return json.dumps({"error": "No object ID provided"}, indent=2) params: Dict[str, Any] = { "fields": _DEFAULT_FIELDS, "level": level, "page_size": int(page_size), } time_params, time_error, normalization_warnings = normalize_time_input(date_range, default_preset="maximum") if time_error: return json.dumps(time_error, indent=2) params.update(time_params or {}) breakdown_params, breakdown_warnings = normalize_breakdown_inputs( breakdown=breakdown, breakdowns=breakdowns, action_breakdowns=action_breakdowns, summary_action_breakdowns=summary_action_breakdowns, ) params.update(breakdown_params) normalization_warnings.extend(breakdown_warnings) if page_cursor: params["page_cursor"] = page_cursor deprecated_windows = _deprecated_windows(action_attribution_windows) if action_attribution_windows: params["action_attribution_windows"] = list(action_attribution_windows) payload = await make_api_request(f"{object_id}/insights", meta_access_token, params) if isinstance(payload, dict): _append_warnings(payload, normalization_warnings) _with_warning(payload, deprecated_windows) if compact and isinstance(payload.get("data"), list): payload["data"] = [ _strip_redundant_actions(row) if isinstance(row, dict) else row for row in payload["data"] ] return json.dumps(payload, indent=2)