meta-ads-mcp

⭐ PREMIUM FEATURE ⭐

Fetches performance insights for multiple ad accounts in parallel.

⚠️ Requires: Premium or Enterprise plan 💡 Value: Analyze performance data across all your campaigns at scale

Args: level: The aggregation level. Supported values: "account", "campaign", "adset" time_range: Time period for insights (default: "last_7d") Preset values: last_7d, last_14d, last_30d, last_90d, this_month, last_month, this_year, last_year, lifetime Or an object with "since" and "until" dates: {"since": "2025-01-01", "until": "2025-12-31"} time_breakdown: Optional time dimension to break down metrics by Supported values: "day", "week", "month" When specified, each account result includes segmented_metrics array with per-period data breakdown: Optional dimension to break down metrics by (can significantly increase response size) Demographic: age, gender, country, region, dma Platform/Device: device_platform, platform_position, publisher_platform, impression_device action_attribution_windows: Optional list of attribution windows for conversion metrics Supported values: 1d_click, 7d_click, 28d_click, 1d_view, 7d_view, 28d_view Default: ["7d_click", "1d_view"] account_ids: Array of account IDs to filter (optional). If omitted, fetches all accounts. fields: Metrics to return in compact mode. Default: ["spend"] Available: spend, impressions, clicks, reach, conversions, ctr, cpc, cpm, frequency, unique_clicks, cost_per_result Example: ["spend", "impressions", "clicks"] returns all three metrics Note: Only used when compact=true. Without compact mode, all fields are returned. use_cache: Whether to use cached data (default: true, disabled when time_breakdown is used) limit: Maximum accounts to return per request (default: 20, max: 50) offset: Number of accounts to skip for pagination (default: 0) compact: When true, returns minimal pivoted data for smaller response size (default: false) ⚡ USE THIS when querying many campaigns to avoid context overflow Returns: campaign_id, campaign_name, and _by_period for each requested field Use "fields" parameter to specify which metrics (default: spend only) Reduces response size by ~95% (from 500KB to ~5KB for 100 campaigns) campaign_name_contains: Array of strings to filter campaigns by name (case-insensitive) Only campaigns whose name contains ANY of these strings are returned Example: ["Prospecting", "Retargeting", "Retention"]

Returns: JSON response with: - summary: {total_accounts, successful, failed, cached, total_campaigns (campaign level), total_adsets (adset level), total_periods (time_breakdown), campaigns_matched, campaigns_total (when filtered)} - results: Array with per-account insights, each including segmented_metrics when time_breakdown is used - filter_applied: The campaign_name_contains filter used (if specified) - fields_included: The metrics included in compact mode response (when compact=true) - execution_time_ms, time_range, time_breakdown (if specified), breakdown (if specified), level, pagination metadata

Example Usage: # Fetch account-level insights for first 20 accounts (default) bulk_get_insights( level="account" )

⭐ PREMIUM FEATURE ⭐

Update multiple ads with individual or uniform parameters. Supports both explicit ID-based updates and filter-based batch updates.

⚠️ Requires: Premium or Enterprise plan 💡 Value: Manage hundreds of ads efficiently and save hours of manual work

Limits: Default limit of 20 entities per operation for safety. Can be increased up to 200 maximum by setting the 'limit' parameter (requires user confirmation for large updates).

Args: account_id: Meta Ads account ID (format: act_XXXXXXXXX) access_token: Meta API access token (optional) dry_run: If true, returns list of entities that would be affected without making changes (default: false) limit: Maximum number of entities to update (default: 20, max: 200). Use higher values with caution and user confirmation

Returns: JSON response with matched/updated/failed/skipped counts and detailed results

Example Usage: # Mode 1: Update specific ads bulk_update_ads( account_id="act_123456", ad_updates=[ {"ad_id": "345", "status": "ACTIVE"}, {"ad_id": "678", "status": "ACTIVE"} ] )

⭐ PREMIUM FEATURE ⭐

Update multiple ad sets with individual or uniform parameters. Supports both explicit ID-based updates and filter-based batch updates.

⚠️ Requires: Premium or Enterprise plan 💡 Value: Efficiently manage ad set configurations and budgets at scale

Limits: Default limit of 20 entities per operation for safety. Can be increased up to 200 maximum by setting the 'limit' parameter (requires user confirmation for large updates).

Args: account_id: Meta Ads account ID (format: act_XXXXXXXXX) access_token: Meta API access token (optional) dry_run: If true, returns list of entities that would be affected without making changes (default: false) limit: Maximum number of entities to update (default: 20, max: 200). Use higher values with caution and user confirmation

Returns: JSON response with matched/updated/failed/skipped counts and detailed results

Example Usage: # Mode 1: Update specific ad sets bulk_update_adsets( account_id="act_123456", adset_updates=[ {"adset_id": "789", "bid_amount": 500}, {"adset_id": "012", "bid_amount": 750, "status": "ACTIVE"} ] )

⭐ PREMIUM FEATURE ⭐

Update multiple campaigns with individual or uniform parameters. Supports both explicit ID-based updates and filter-based batch updates.

⚠️ Requires: Premium or Enterprise plan 💡 Value: Manage multiple campaigns at scale and automate optimization tasks

Limits: Default limit of 20 entities per operation for safety. Can be increased up to 200 maximum by setting the 'limit' parameter (requires user confirmation for large updates).

Args: account_id: Meta Ads account ID (format: act_XXXXXXXXX) access_token: Meta API access token (optional) dry_run: If true, returns list of entities that would be affected without making changes (default: false) limit: Maximum number of entities to update (default: 20, max: 200). Use higher values with caution and user confirmation

Returns: JSON response with matched/updated/failed/skipped counts and detailed results

Example Usage: # Mode 1: Update specific campaigns bulk_update_campaigns( account_id="act_123456", campaign_updates=[ {"campaign_id": "123", "status": "PAUSED"}, {"campaign_id": "456", "status": "PAUSED", "daily_budget": 15000} ] )

Create a new ad with an existing creative.

Args: account_id: Meta Ads account ID (format: act_XXXXXXXXX) name: Ad name adset_id: Ad set ID where this ad will be placed creative_id: ID of an existing creative to use status: Initial ad status (default: PAUSED) bid_amount: Optional bid amount in account currency (in cents) tracking_specs: Optional tracking specifications (e.g., for pixel events). Example: [{"action.type":"offsite_conversion","fb_pixel":["YOUR_PIXEL_ID"]}] access_token: Meta API access token (optional - will use cached token if not provided)

Note: Dynamic Creative creatives require the parent ad set to have is_dynamic_creative=true. Otherwise, ad creation will fail with error_subcode 1885998.

Create a new ad creative using an uploaded image hash or video ID.

Supports three creative modes:

• Simple image/video: Single image_hash or video_id with object_story_spec

• Dynamic Creative: Multiple variants with dynamic_creative_spec (requires is_dynamic_creative on ad set)

• FLEX/DOF (Advantage+): Set optimization_type="DEGREES_OF_FREEDOM" for Meta to auto-optimize across all asset combinations without requiring is_dynamic_creative on the ad set

Args: account_id: Meta Ads account ID (format: act_XXXXXXXXX) image_hash: Hash of a single uploaded image (cannot be used with image_hashes or video_id) access_token: Meta API access token (optional - will use cached token if not provided) name: Creative name page_id: Facebook Page ID (string or int; coerced to string) link_url: Destination URL for the ad (required unless using lead_gen_form_id) message: Single ad copy/text (cannot be used with messages) messages: List of primary text variants for FLEX/dynamic creatives (cannot be used with message) headline: Single headline for simple ads (cannot be used with headlines) headlines: List of headlines for dynamic creative testing (cannot be used with headline) description: Single description for simple ads (cannot be used with descriptions) descriptions: List of descriptions for dynamic creative testing (cannot be used with description) image_hashes: List of image hashes for FLEX creatives (up to 10, cannot be used with image_hash or video_id) video_id: Meta video ID for video creatives (cannot be used with image_hash or image_hashes). Upload a video first via the Meta API, then use the returned video ID here. thumbnail_url: Thumbnail image URL for video creatives. Recommended when using video_id. Meta will auto-generate a thumbnail if not provided. optimization_type: Set to "DEGREES_OF_FREEDOM" for FLEX (Advantage+) creatives that allow Meta to auto-optimize across all asset combinations. When using DEGREES_OF_FREEDOM, at least one asset field (image_hashes, messages, headlines, or descriptions) must contain more than one variant. dynamic_creative_spec: Dynamic creative optimization settings call_to_action_type: Call to action button type (e.g., 'LEARN_MORE', 'SIGN_UP', 'SHOP_NOW') lead_gen_form_id: Lead generation form ID for lead generation campaigns. Required when using lead generation CTAs like 'SIGN_UP', 'GET_OFFER', 'SUBSCRIBE', etc. instagram_actor_id: Optional Instagram account ID for Instagram placements. Sent as instagram_user_id inside object_story_spec (Meta deprecated instagram_actor_id in Jan 2026). ad_formats: List of ad format strings for asset_feed_spec (e.g., ["AUTOMATIC_FORMAT"] for Flexible ads, ["SINGLE_IMAGE"] for single image, ["SINGLE_VIDEO"] for video). When optimization_type is "DEGREES_OF_FREEDOM" with image_hashes, defaults to ["AUTOMATIC_FORMAT"] (Flexible format). For video creatives, defaults to ["SINGLE_VIDEO"]. Otherwise defaults to ["SINGLE_IMAGE"]. asset_customization_rules: List of placement-specific asset overrides for asset_feed_spec. Lets you assign different images or videos to specific placement groups (e.g., feed vs. stories). Only valid with image_hashes or plural asset params. Each rule uses a user-friendly format that is automatically translated to Meta's API format (adlabels + customization_spec positions): - placement_groups: list of placement group names Valid values: FEED, STORY, MESSENGER, INSTREAM_VIDEO, SEARCH, SHOP, AUDIENCE_NETWORK - customization_spec: dict specifying the asset to use for those placements Supported keys: image_hashes (list), video_ids (list), bodies, titles, descriptions (text overrides) All image hashes referenced in rules must also be in image_hashes. Example (feed gets one image, stories gets another): [ {"placement_groups": ["FEED"], "customization_spec": {"image_hashes": ["<feed_hash>"]}}, {"placement_groups": ["STORY"], "customization_spec": {"image_hashes": ["<story_hash>"]}} ]

Returns: JSON response with created creative details

Create a new ad set in a Meta Ads account.

Args: account_id: Meta Ads account ID (format: act_XXXXXXXXX) campaign_id: Meta Ads campaign ID this ad set belongs to name: Ad set name optimization_goal: Conversion optimization goal (e.g., 'LINK_CLICKS', 'REACH', 'CONVERSIONS', 'APP_INSTALLS', 'VALUE') billing_event: How you're charged (e.g., 'IMPRESSIONS', 'LINK_CLICKS') status: Initial ad set status (default: PAUSED) daily_budget: Daily budget in account currency (in cents) as a string lifetime_budget: Lifetime budget in account currency (in cents) as a string targeting: Targeting specs (age, location, interests, etc). targeting_automation.advantage_audience defaults to 0 if not set (Meta API v24+ requirement). Set to 1 to enable Advantage+ Audience (requires age_max>=65). Use search_interests for interest IDs. bid_amount: Bid amount in account currency (in cents). REQUIRED for: LOWEST_COST_WITH_BID_CAP, COST_CAP, TARGET_COST. NOT USED by: LOWEST_COST_WITH_MIN_ROAS (uses bid_constraints instead). May also be required if the parent campaign's bid strategy requires it. bid_strategy: Bid strategy. Valid values: - 'LOWEST_COST_WITHOUT_CAP' (recommended) - no bid_amount required - 'LOWEST_COST_WITH_BID_CAP' - REQUIRES bid_amount - 'COST_CAP' - REQUIRES bid_amount - 'LOWEST_COST_WITH_MIN_ROAS' - REQUIRES bid_constraints with roas_average_floor, and optimization_goal='VALUE'. Does NOT use bid_amount. Note: 'LOWEST_COST' is NOT valid - use 'LOWEST_COST_WITHOUT_CAP'. Campaign-level bid strategy may constrain ad set choices. bid_constraints: Bid constraints dict. Required for LOWEST_COST_WITH_MIN_ROAS. Use {"roas_average_floor": } where value = target ROAS * 10000. Example: 2.0x ROAS -> {"roas_average_floor": 20000} start_time: Start time in ISO 8601 format (e.g., '2023-12-01T12:00:00-0800') end_time: End time in ISO 8601 format dsa_beneficiary: DSA beneficiary for European compliance promoted_object: App config for APP_INSTALLS. Required: application_id, object_store_url. destination_type: Where users go after click. Common values: 'WEBSITE', 'WHATSAPP', 'MESSENGER', 'INSTAGRAM_DIRECT', 'ON_AD', 'APP', 'FACEBOOK', 'SHOP_AUTOMATIC'. Also supports multi-channel combos like 'MESSAGING_MESSENGER_WHATSAPP'. is_dynamic_creative: Enable Dynamic Creative for this ad set. access_token: Meta API access token (optional - will use cached token if not provided)

Create a budget schedule for a Meta Ads campaign.

Allows scheduling budget increases based on anticipated high-demand periods. The times should be provided as Unix timestamps.

Args: campaign_id: Meta Ads campaign ID. budget_value: Amount of budget increase. Interpreted based on budget_value_type. budget_value_type: Type of budget value - "ABSOLUTE" or "MULTIPLIER". time_start: Unix timestamp for when the high demand period should start. time_end: Unix timestamp for when the high demand period should end. access_token: Meta API access token (optional - will use cached token if not provided).

Returns: A JSON string containing the ID of the created budget schedule or an error message.

Create a new campaign in a Meta Ads account.

Args: account_id: Meta Ads account ID (format: act_XXXXXXXXX) name: Campaign name objective: Campaign objective (ODAX, outcome-based). Must be one of: OUTCOME_AWARENESS, OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_APP_PROMOTION. Note: Legacy objectives like BRAND_AWARENESS, LINK_CLICKS, CONVERSIONS, APP_INSTALLS, etc. are not valid for new campaigns and will cause a 400 error. Use the outcome-based values above (e.g., BRAND_AWARENESS → OUTCOME_AWARENESS). access_token: Meta API access token (optional - will use cached token if not provided) status: Initial campaign status (default: PAUSED) special_ad_categories: List of special ad categories if applicable daily_budget: Daily budget in account currency (in cents) as a string (only used if use_adset_level_budgets=False) lifetime_budget: Lifetime budget in account currency (in cents) as a string (only used if use_adset_level_budgets=False) buying_type: Buying type (e.g., 'AUCTION') bid_strategy: Bid strategy. Must be one of: 'LOWEST_COST_WITHOUT_CAP', 'LOWEST_COST_WITH_BID_CAP', 'COST_CAP', 'LOWEST_COST_WITH_MIN_ROAS'. bid_cap: Bid cap in account currency (in cents) as a string spend_cap: Spending limit for the campaign in account currency (in cents) as a string campaign_budget_optimization: Whether to enable campaign budget optimization (only used if use_adset_level_budgets=False) ab_test_control_setups: Settings for A/B testing (e.g., [{"name":"Creative A", "ad_format":"SINGLE_IMAGE"}]) use_adset_level_budgets: If True, budgets will be set at the ad set level instead of campaign level (default: False)

⭐ PREMIUM FEATURE ⭐

Create a carousel ad creative with multiple images/videos (2-10 cards). Carousel ads allow users to swipe through multiple images or videos in a single ad unit.

⚠️ Requires: Premium or Enterprise plan 💡 Value: Create engaging multi-card ads that showcase multiple products or tell a story

Args: account_id: Meta Ads account ID (format: act_XXXXXXXXX) - required page_id: Facebook Page ID to associate with the creative - required child_attachments: Array of 2-10 cards for the carousel - required [{ "link": "URL for this card (required)", "image_hash": "Image hash from upload_ad_image (required if no video_id)", "video_id": "Video ID (required if no image_hash)", "name": "Headline text (optional, max 40 chars)", "description": "Description text (optional, max 20 chars)", "call_to_action": {"type": "SHOP_NOW", "value": {"link": "..."}} (optional) }] message: Primary text shown above the carousel (optional) link: Default destination URL (optional, defaults to first card's link) call_to_action_type: Global CTA type (optional) Options: SHOP_NOW, LEARN_MORE, BOOK_NOW, DOWNLOAD, GET_QUOTE, SUBSCRIBE, WATCH_MORE multi_share_end_card: Show end card with Page profile photo (optional, default: true) multi_share_optimized: Let Meta optimize card order (optional, default: true) instagram_actor_id: Instagram account ID for Instagram placement (optional) access_token: Meta API access token (optional)

Returns: JSON response with success status, creative_id, and details

Example Usage: # Create a basic carousel with 3 product cards create_carousel_ad_creative( account_id="act_123456", page_id="987654321", child_attachments=[ {"link": "https://shop.com/product1", "image_hash": "abc123", "name": "Product 1", "description": "Only $19.99"}, {"link": "https://shop.com/product2", "image_hash": "def456", "name": "Product 2", "description": "Only $29.99"}, {"link": "https://shop.com/product3", "image_hash": "ghi789", "name": "Product 3", "description": "Only $39.99"} ], message="Check out our best sellers!", call_to_action_type="SHOP_NOW" )

Send a professional AI-powered email report analyzing your Meta Ads performance. Your first report is FREE - no subscription needed! Just use cadence "once".

Modes:

• cadence "once": Send a single report now. Free users get 1 free report. Paid users: up to 3/month.

• cadence "daily": Daily email reports (Pro plan+). First report sent immediately.

• cadence "weekly": Weekly email reports (Pro plan+). First report sent immediately.

The report covers campaign performance, budget optimization, audience insights, and creative recommendations.

Args: account_id (required): Meta Ads account ID (format: act_XXXXXXXXX) cadence (required): "once" | "daily" | "weekly" emails (optional): Recipient email addresses (max 5). Defaults to your account email if omitted. time_range (optional): Default "last_7d". Options: last_1d, last_3d, last_7d, last_14d, last_30d language (optional): Default "English" day_of_week (optional): For weekly only. 0=Sunday through 6=Saturday preferred_hour_utc (optional): Delivery hour (0-23 UTC). Default 8

Duplicate a Meta Ads ad.

Recommended: Use this to run robust experiments.

Args: ad_id: Meta Ads ad ID to duplicate target_adset_id: Ad set ID to move the duplicated ad to (optional) name_suffix: Suffix to add to the duplicated ad name duplicate_creative: Whether to duplicate the ad creative new_creative_name: Override name for the duplicated creative new_status: Status for the new ad (ACTIVE or PAUSED)

Duplicate a Meta Ads ad set with its ads.

Recommended: Use this to run robust experiments.

Args: adset_id: Meta Ads ad set ID to duplicate target_campaign_id: Campaign ID to move the duplicated ad set to (optional) name_suffix: Suffix to add to the duplicated ad set name include_ads: Whether to duplicate ads within the ad set include_creatives: Whether to duplicate ad creatives new_daily_budget: Override the daily budget for the new ad set new_targeting: Override targeting settings for the new ad set new_status: Status for the new ad set (ACTIVE or PAUSED)

Duplicate a Meta Ads campaign with all its ad sets and ads.

Recommended: Use this to run robust experiments.

Args: campaign_id: Meta Ads campaign ID to duplicate name_suffix: Suffix to add to the duplicated campaign name include_ad_sets: Whether to duplicate ad sets within the campaign include_ads: Whether to duplicate ads within ad sets include_creatives: Whether to duplicate ad creatives copy_schedule: Whether to copy the campaign schedule new_daily_budget: Override the daily budget for the new campaign new_status: Status for the new campaign (ACTIVE or PAUSED)

Duplicate a Meta Ads creative.

Recommended: Use this to run robust experiments.

Args: creative_id: Meta Ads creative ID to duplicate name_suffix: Suffix to add to the duplicated creative name new_primary_text: Override the primary text for the new creative new_headline: Override the headline for the new creative new_description: Override the description for the new creative new_cta_type: Override the call-to-action type for the new creative new_destination_url: Override the destination URL for the new creative

Estimate audience size for targeting specifications using Meta's delivery_estimate API.

This function provides comprehensive audience estimation for complex targeting combinations including demographics, geography, interests, and behaviors. It also maintains backwards compatibility for simple interest validation.

Args: access_token: Meta API access token (optional - will use cached token if not provided) account_id: Meta Ads account ID (format: act_XXXXXXXXX) - required for comprehensive estimation targeting: Complete targeting specification including demographics, geography, interests, etc. Example: { "age_min": 25, "age_max": 65, "geo_locations": {"countries": ["PL"]}, "flexible_spec": [ {"interests": [{"id": "6003371567474"}]}, {"interests": [{"id": "6003462346642"}]} ] } optimization_goal: Optimization goal for estimation (default: "REACH"). Options: "REACH", "LINK_CLICKS", "IMPRESSIONS", "CONVERSIONS", etc. interest_list: [DEPRECATED - for backwards compatibility] List of interest names to validate interest_fbid_list: [DEPRECATED - for backwards compatibility] List of interest IDs to validate

Returns: JSON string with audience estimation results including estimated_audience_size, reach_estimate, and targeting validation

Fetch complete record data by ID. It retrieves the full data for a specific record identified by its ID.

Args: id: The record ID to fetch (format: "type:id", e.g., "account:act_123456")

Returns: JSON response with complete record data including id, title, text, and metadata

Example Usage: fetch(id="account:act_123456789") fetch(id="campaign:23842588888640185") fetch(id="ad:23842614006130185") fetch(id="page:123456789")

Get detailed information about a specific ad account.

Args: account_id: Meta Ads account ID (format: act_XXXXXXXXX) access_token: Meta API access token (optional - will use cached token if not provided)

Get pages associated with a Meta Ads account.

Args: account_id: Meta Ads account ID (format: act_XXXXXXXXX) access_token: Meta API access token (optional - will use cached token if not provided)

Returns: JSON response with pages associated with the account

Get ad accounts accessible by a user.

amount_spent and balance are returned in currency units (e.g. USD dollars), not cents.

Args: access_token: Meta API access token (optional - will use cached token if not provided) user_id: Meta user ID or "me" for the current user limit: Maximum number of accounts to return (default: 200)

Get creative details for a specific ad. Requires an ad_id (not account_id). Use get_ads first to find ad IDs.

Args: ad_id: Meta Ads ad ID (required) access_token: Meta API access token (optional - will use cached token if not provided)

Get detailed information about a specific ad.

Args: ad_id: Meta Ads ad ID access_token: Meta API access token (optional - will use cached token if not provided)

Get, download, and visualize a Meta ad image in one step. Useful to see the image in the LLM.

Args: ad_id: Meta Ads ad ID access_token: Meta API access token (optional - will use cached token if not provided)

Returns: The ad image ready for direct visual analysis

Get ads for a Meta Ads account with optional filtering.

Args: account_id: Meta Ads account ID (format: act_XXXXXXXXX) access_token: Meta API access token (optional - will use cached token if not provided) limit: Maximum number of ads to return (default: 10) campaign_id: Optional campaign ID to filter by adset_id: Optional ad set ID to filter by

Get detailed information about a specific ad set.

Args: adset_id: Meta Ads ad set ID access_token: Meta API access token (optional - will use cached token if not provided)

Example: To call this function through MCP, pass the adset_id as the first argument: { "args": "YOUR_ADSET_ID" }

Get ad sets for a Meta Ads account with optional filtering by campaign.

Args: account_id: Meta Ads account ID (format: act_XXXXXXXXX) access_token: Meta API access token (optional - will use cached token if not provided) limit: Maximum number of ad sets to return (default: 10) campaign_id: Optional campaign ID to filter by

Get detailed information about a specific campaign.

Note: This function requests a specific set of fields ('id,name,objective,status,...'). The Meta API offers many other fields for campaigns (e.g., 'effective_status', 'source_campaign_id', etc.) that could be added to the 'fields' parameter in the code if needed.

Args: campaign_id: Meta Ads campaign ID access_token: Meta API access token (optional - will use cached token if not provided)

Get campaigns for a Meta Ads account with optional filtering.

Note: By default, the Meta API returns a subset of available fields. Other fields like 'effective_status', 'special_ad_categories', 'lifetime_budget', 'spend_cap', 'budget_remaining', 'promoted_object', 'source_campaign_id', etc., might be available but require specifying them in the API call (currently not exposed by this tool's parameters).

Args: account_id: Meta Ads account ID (format: act_XXXXXXXXX) access_token: Meta API access token (optional - will use cached token if not provided) limit: Maximum number of campaigns to return (default: 10) status_filter: Filter by effective status (e.g., 'ACTIVE', 'PAUSED', 'ARCHIVED'). Maps to the 'effective_status' API parameter, which expects an array (this function handles the required JSON formatting). Leave empty for all statuses. objective_filter: Filter by campaign objective(s). Can be a single objective string or a list of objectives. Valid objectives: 'OUTCOME_AWARENESS', 'OUTCOME_TRAFFIC', 'OUTCOME_ENGAGEMENT', 'OUTCOME_LEADS', 'OUTCOME_SALES', 'OUTCOME_APP_PROMOTION'. Examples: 'OUTCOME_LEADS' or ['OUTCOME_LEADS', 'OUTCOME_SALES']. Leave empty for all objectives. after: Pagination cursor to get the next set of results

Get detailed information about a specific ad creative by its ID.

Args: creative_id: Meta Ads creative ID (required) access_token: Meta API access token (optional)

Get performance insights for a campaign, ad set, ad or account.

Args: object_id: ID of the campaign, ad set, ad or account access_token: Meta API access token (optional - will use cached token if not provided) time_range: Either a preset time range string or a dictionary with "since" and "until" dates in YYYY-MM-DD format Preset options: today, yesterday, this_month, last_month, this_quarter, maximum, data_maximum, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year Dictionary example: {"since":"2023-01-01","until":"2023-01-31"} time_breakdown: Optional time dimension to break down metrics by Supported values: "day", "week", "month" - day: Daily breakdown (returns metrics for each day in the range) - week: Weekly breakdown (returns metrics for each week) - month: Monthly breakdown (returns metrics for each month) When specified, returns segmented_metrics array with per-period data plus aggregates breakdown: Optional breakdown dimension. Valid values include: Demographic: age, gender, country, region, dma Platform/Device: device_platform, platform_position, publisher_platform, impression_device Creative Assets: ad_format_asset, body_asset, call_to_action_asset, description_asset, image_asset, link_url_asset, title_asset, video_asset, media_asset_url, media_creator, media_destination_url, media_format, media_origin_url, media_text_content, media_type level: Level of aggregation (ad, adset, campaign, account) limit: Maximum number of results to return per page (default: 25) after: Pagination cursor to get the next set of results action_attribution_windows: Optional list of attribution windows (e.g., ["1d_click", "7d_click", "1d_view"])

Returns: When time_breakdown is NOT specified: Standard Meta Insights API response with aggregated metrics for the entire period

Example Usage: # Get last 30 days aggregated (default behavior) get_insights( object_id="act_123456789", time_range="last_30d", level="account" )

Get Instagram business accounts associated with an ad account that can be used as instagram_actor_id when creating ad creatives.

Args: account_id: Meta Ads account ID (format: act_XXXXXXXXX)

Returns: List of Instagram accounts with id, username, name, profile_picture_url, and followers_count

Get interest suggestions based on existing interests.

Args: interest_list: List of interest names to get suggestions for (e.g., ["Basketball", "Soccer"]) access_token: Meta API access token (optional - will use cached token if not provided)
limit: Maximum number of suggestions to return (default: 25)

Returns: JSON string containing suggested interests with id, name, audience_size, and description fields

Search through Meta Ads data and return matching record IDs. It searches across ad accounts, campaigns, ads, pages, and businesses to find relevant records based on the provided query.

Args: query: Search query string to find relevant Meta Ads records access_token: Meta API access token (optional - will use cached token if not provided)

Returns: JSON response with list of matching record IDs

Example Usage: search(query="active campaigns") search(query="account spending") search(query="facebook ads performance") search(query="facebook pages") search(query="user businesses")

Get all available behavior targeting options.

Args: access_token: Meta API access token (optional - will use cached token if not provided) limit: Maximum number of results to return (default: 50)

Returns: JSON string containing behavior targeting options with id, name, audience_size bounds, path, and description

Get demographic targeting options.

Args: access_token: Meta API access token (optional - will use cached token if not provided) demographic_class: Type of demographics to retrieve. Options: 'demographics', 'life_events', 'industries', 'income', 'family_statuses', 'user_device', 'user_os' (default: 'demographics') limit: Maximum number of results to return (default: 50)

Returns: JSON string containing demographic targeting options with id, name, audience_size bounds, path, and description

Search for geographic targeting locations.

Args: query: Search term for locations (e.g., "New York", "California", "Japan") access_token: Meta API access token (optional - will use cached token if not provided) location_types: Types of locations to search. Options: ['country', 'region', 'city', 'zip', 'geo_market', 'electoral_district']. If not specified, searches all types. limit: Maximum number of results to return (default: 25)

Returns: JSON string containing location data with key, name, type, and geographic hierarchy information

Search for interest targeting options by keyword.

Args: query: Search term for interests (e.g., "baseball", "cooking", "travel") access_token: Meta API access token (optional - will use cached token if not provided) limit: Maximum number of results to return (default: 25)

Returns: JSON string containing interest data with id, name, audience_size, and path fields

Search for pages by name within an account.

Args: account_id: Meta Ads account ID (format: act_XXXXXXXXX) access_token: Meta API access token (optional - will use cached token if not provided) search_term: Search term to find pages by name (optional - returns all pages if not provided)

Returns: JSON response with matching pages

Update an ad with new settings.

Args: ad_id: Meta Ads ad ID status: Update ad status (ACTIVE, PAUSED, etc.) bid_amount: Bid amount in account currency (in cents for USD) tracking_specs: Optional tracking specifications (e.g., for pixel events). creative_id: ID of the creative to associate with this ad (changes the ad's image/content) access_token: Meta API access token (optional - will use cached token if not provided)

Update an existing ad creative's name or optimization settings.

IMPORTANT — Meta API limitation: The Meta API does NOT allow updating content fields (message, headline, description, CTA, image, video, URL) on existing creatives. Only the creative name and optimization settings (asset_feed_spec) can be changed. To change ad content, create a new creative with the desired content and update the ad to reference the new creative via update_ad.

Args: creative_id: Meta Ads creative ID to update access_token: Meta API access token (optional - will use cached token if not provided) name: New creative name (this is the most reliable update) message: New ad copy/text — NOTE: Meta API may reject this on existing creatives messages: List of primary text variants — NOTE: Meta API may reject this on existing creatives headline: Single headline — NOTE: Meta API may reject this on existing creatives headlines: New list of headlines — NOTE: Meta API may reject this on existing creatives description: Single description — NOTE: Meta API may reject this on existing creatives descriptions: New list of descriptions — NOTE: Meta API may reject this on existing creatives optimization_type: Set to "DEGREES_OF_FREEDOM" for FLEX (Advantage+) creatives dynamic_creative_spec: New dynamic creative optimization settings call_to_action_type: New call to action button type — NOTE: Meta API may reject this on existing creatives lead_gen_form_id: Lead generation form ID for lead generation campaigns ad_formats: List of ad format strings for asset_feed_spec (e.g., ["AUTOMATIC_FORMAT"] for Flexible ads, ["SINGLE_IMAGE"] for single image)

Returns: JSON response with updated creative details

Update an ad set with new settings including frequency caps and budgets.

Args: adset_id: Meta Ads ad set ID frequency_control_specs: Frequency control specs (e.g. [{"event": "IMPRESSIONS", "interval_days": 7, "max_frequency": 3}]) bid_strategy: Bid strategy. Valid values: - 'LOWEST_COST_WITHOUT_CAP' (recommended) - no bid_amount required - 'LOWEST_COST_WITH_BID_CAP' - REQUIRES bid_amount - 'COST_CAP' - REQUIRES bid_amount - 'LOWEST_COST_WITH_MIN_ROAS' - REQUIRES bid_constraints with roas_average_floor Note: 'LOWEST_COST' is NOT valid - use 'LOWEST_COST_WITHOUT_CAP'. bid_amount: Bid amount in cents. Required for LOWEST_COST_WITH_BID_CAP, COST_CAP, TARGET_COST. NOT USED by LOWEST_COST_WITH_MIN_ROAS (uses bid_constraints instead). bid_constraints: Bid constraints dict. Required for LOWEST_COST_WITH_MIN_ROAS. Use {"roas_average_floor": } where value = target ROAS * 10000. Example: 2.0x ROAS -> {"roas_average_floor": 20000} status: Update ad set status (ACTIVE, PAUSED, etc.) targeting: Complete targeting specifications (replaces existing targeting) optimization_goal: Conversion optimization goal (e.g., 'LINK_CLICKS', 'CONVERSIONS', 'VALUE') daily_budget: Daily budget in account currency (in cents) lifetime_budget: Lifetime budget in account currency (in cents) is_dynamic_creative: Enable/disable Dynamic Creative for this ad set. access_token: Meta API access token (optional - will use cached token if not provided)

Update an existing campaign in a Meta Ads account.

Args: campaign_id: Meta Ads campaign ID access_token: Meta API access token (optional - will use cached token if not provided) name: New campaign name status: New campaign status (e.g., 'ACTIVE', 'PAUSED') special_ad_categories: List of special ad categories if applicable daily_budget: New daily budget in account currency (in cents) as a string. Set to empty string "" to remove the daily budget. lifetime_budget: New lifetime budget in account currency (in cents) as a string. Set to empty string "" to remove the lifetime budget. bid_strategy: New bid strategy bid_cap: New bid cap in account currency (in cents) as a string spend_cap: New spending limit for the campaign in account currency (in cents) as a string campaign_budget_optimization: Enable/disable campaign budget optimization objective: New campaign objective (Note: May not always be updatable) use_adset_level_budgets: If True, removes campaign-level budgets to switch to ad set level budgets

Upload an image to use in Meta Ads creatives.

Args: account_id: Meta Ads account ID (format: act_XXXXXXXXX) access_token: Meta API access token (optional - will use cached token if not provided) file: Data URL or raw base64 string of the image (e.g., "data:image/png;base64,iVBORw0KG...") image_url: Direct URL to an image to fetch and upload name: Optional name for the image (default: filename)

Returns: JSON response with image details including hash for creative creation