estimate_audience_size
Calculate potential audience reach for Meta Ads targeting specifications or validate deprecated interest-based targeting lists.
Instructions
Estimate audience size for targeting specs or validate deprecated interest-list mode.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| meta_access_token | No | ||
| ad_account_id | No | ||
| targeting | No | ||
| optimization_goal | No | REACH | |
| interest_list | No | ||
| interest_fbid_list | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- The handler function that implements the 'estimate_audience_size' tool.
async def estimate_audience_size( meta_access_token: Optional[str] = None, ad_account_id: Optional[str] = None, targeting: Optional[Dict[str, Any]] = None, optimization_goal: str = "REACH", interest_list: Optional[List[str]] = None, interest_fbid_list: Optional[List[str]] = None, ) -> str: """Estimate audience size for targeting specs or validate deprecated interest-list mode.""" deprecated_interest_mode = _deprecated_interest_validation_mode( ad_account_id=ad_account_id, targeting=targeting, interest_list=interest_list, interest_fbid_list=interest_fbid_list, ) if deprecated_interest_mode and not targeting: if not (interest_list or interest_fbid_list): return _as_json({"error": "No interest list or FBID list provided"}) deprecated_interest_payload: Dict[str, Any] = {"type": "adinterestvalid"} if interest_list: deprecated_interest_payload["interest_list"] = json.dumps(list(interest_list)) if interest_fbid_list: deprecated_interest_payload["interest_fbid_list"] = json.dumps(list(interest_fbid_list)) payload = await make_api_request( "search", meta_access_token, deprecated_interest_payload, ) return _as_json(payload) if not ad_account_id: return _as_json( { "error": "ad_account_id is required for comprehensive audience estimation", "details": "For simple interest validation, use interest_list or interest_fbid_list parameters", } ) if not targeting: return _as_json( { "error": "targeting specification is required for comprehensive audience estimation", "example": { "age_min": 25, "age_max": 65, "geo_locations": {"countries": ["US"]}, "flexible_spec": [{"interests": [{"id": "6003371567474"}]}], }, } ) if not _has_location_or_custom_audience(targeting): return _as_json( { "error": "Missing target audience location", "details": "Select at least one location in targeting.geo_locations or include a custom audience.", "action_required": "Add geo_locations with countries/regions/cities/zips or include custom_audiences.", "example": { "geo_locations": {"countries": ["US"]}, "age_min": 25, "age_max": 65, }, } ) fallback_disabled = os.environ.get("META_MCP_DISABLE_DELIVERY_FALLBACK", "1") == "1" try: reach_payload = await make_api_request( f"{ad_account_id}/reachestimate", meta_access_token, {"targeting_spec": targeting}, method="GET", ) if isinstance(reach_payload, dict) and reach_payload.get("error"): graph_error = _extract_graph_error(reach_payload) missing_location = _missing_location_error_payload(graph_error, ad_account_id) if missing_location: return _as_json(missing_location) if fallback_disabled: return _as_json( { "error": "Graph API returned an error for reachestimate", "details": reach_payload.get("error"), "endpoint_used": f"{ad_account_id}/reachestimate", "request_params": {"has_targeting_spec": bool(targeting)}, "note": "delivery_estimate fallback disabled via META_MCP_DISABLE_DELIVERY_FALLBACK", } ) fallback_result = await _run_delivery_estimate_fallback( ad_account_id=ad_account_id, meta_access_token=meta_access_token, targeting=targeting, optimization_goal=optimization_goal, ) if fallback_result.get("success"): return _as_json(fallback_result) return _as_json( { "error": "Graph API returned an error for reachestimate; delivery_estimate fallback did not return usable data", "reachestimate_error": reach_payload.get("error"), "fallback_endpoint_used": "delivery_estimate", "fallback_raw_response": fallback_result, "endpoint_used": f"{ad_account_id}/reachestimate", } ) normalized = _normalize_reach_result( reach_payload, ad_account_id=ad_account_id, targeting=targeting, optimization_goal=optimization_goal, ) return _as_json(normalized) except Exception as exc: # noqa: BLE001 if not fallback_disabled: try: fallback_result = await _run_delivery_estimate_fallback( ad_account_id=ad_account_id, meta_access_token=meta_access_token, targeting=targeting, optimization_goal=optimization_goal, ) if fallback_result.get("success"): return _as_json(fallback_result) except Exception: # noqa: BLE001 pass return _as_json( { "error": f"Failed to get audience estimation from reachestimate endpoint: {exc}", "details": "Check targeting parameters and account permissions", "error_type": "general_api_error", "endpoint_used": f"{ad_account_id}/reachestimate", } )