Meta Ads (Marketing API v26.0)

PREREQUISITE: Read ../_mureo-shared/SKILL.md for auth, global flags, and security rules.

Tool names below refer to the built-in platforms; a namespaced variant (see _mureo-shared → Namespaced built-in variants) is used with its prefix substituted.

Tool Summary

Key Differences from Google Ads

API Resources

campaigns

• list -- List all campaigns in the ad account.

  Required: account_id (string, "act_XXXX" format)
  Optional: status_filter (string: "ACTIVE" | "PAUSED"), limit (integer, default: 50)

• get -- Get detailed information about a specific campaign.

  Required: account_id, campaign_id

• create -- Create a new campaign. Requires user confirmation.

  Required: account_id, name, objective
  Optional: status (default: "PAUSED"), daily_budget (integer, in cents), lifetime_budget (integer, in cents)

  Objective options: CONVERSIONS, LINK_CLICKS, REACH, BRAND_AWARENESS, VIDEO_VIEWS, LEAD_GENERATION, MESSAGES, APP_INSTALLS
• update -- Update campaign settings. Requires user confirmation.

  Required: account_id, campaign_id
  Optional: name, status, daily_budget (integer, in cents)

• pause -- Pause a campaign. Requires user confirmation.

  Required: account_id, campaign_id

• enable -- Enable a paused campaign. Requires user confirmation.

  Required: account_id, campaign_id

ad_sets

• list -- List ad sets, optionally filtered by campaign.

  Required: account_id
  Optional: campaign_id, limit (integer, default: 50)

• get -- Get ad set details.

  Required: account_id, ad_set_id

• create -- Create an ad set with targeting and budget. Requires user confirmation.

  Required: account_id, campaign_id, name, daily_budget (integer, in cents)
  Optional: billing_event (default: "IMPRESSIONS"), optimization_goal (default: "REACH"),
            targeting (object), status (default: "PAUSED")

  Optimization goals: REACH, IMPRESSIONS, OFFSITE_CONVERSIONS, LINK_CLICKS, LANDING_PAGE_VIEWS, LEAD_GENERATION, VALUE

  Since Marketing API v26.0, an ad set under a special-ad-category campaign (HOUSING, EMPLOYMENT, CREDIT, FINANCIAL_PRODUCTS_SERVICES) whose targeting is relaxable is rejected unless targeting.targeting_automation.advantage_audience is set to 1 or 0 — targeting is passed through as-is, so set it inside targeting.

• update -- Update ad set settings. Requires user confirmation.

  Required: account_id, ad_set_id
  Optional: name, status, daily_budget (integer, in cents), targeting (object)

• pause -- Pause an ad set. Requires user confirmation.

  Required: account_id, ad_set_id

• enable -- Enable a paused ad set. Requires user confirmation.

  Required: account_id, ad_set_id

ads

• list -- List ads, optionally filtered by ad set.

  Required: account_id
  Optional: ad_set_id, limit (integer, default: 50)

• get -- Get ad details.

  Required: account_id, ad_id

• create -- Create an ad linking to an existing creative. Requires user confirmation.

  Required: account_id, ad_set_id, name, creative_id
  Optional: status (default: "PAUSED")

• update -- Update ad name or status. Requires user confirmation.

  Required: account_id, ad_id
  Optional: name, status ("ACTIVE" | "PAUSED")

• pause -- Pause an ad. Requires user confirmation.

  Required: account_id, ad_id

• enable -- Enable a paused ad. Requires user confirmation.

  Required: account_id, ad_id

excluded_placements

Delivery-surface exclusions: which publishers, Audience Network app categories and content types an ad set must not be delivered against. Meta stores these inside the ad set's targeting spec, but they get their own tools so mureo can record the change with an observation_due window and reverse it — a generic ad_sets.update targeting write is indistinguishable from any other targeting edit.

• get -- Read the ad set's current exclusion lists. Always returns all three keys; an unset facet reads as an empty array.

  Required: account_id, ad_set_id

• set -- Replace the supplied exclusion facets. Requires user confirmation. Each supplied facet REPLACES its current value (Meta has no append here) — call get first and send the full intended set. An omitted facet is left untouched; an empty array clears it. The rest of the targeting spec is preserved by a read-modify-write merge.

  Required: account_id, ad_set_id
  Optional: excluded_publisher_categories, excluded_publisher_list_ids,
            excluded_brand_safety_content_types (arrays of string; at least one required)

  Delivery impact is not measurable here, and mureo says so (#547). None of Meta's insights breakdowns attribute past delivery to publisher categories, publisher block lists or brand-safety content types — publisher_platform / platform_position are a different exclusion surface (ad-set targeting). So analysis_exclusion_impact_preview reports coverage: "unknown" for this tool, never "no impact", and the call's own result carries the same verdict. Tell the operator the size is unknown rather than implying it is small. An operator who would rather refuse than proceed blind sets block_exclusions_without_impact_data: true in STRATEGY.md ## Guardrails, which refuses this tool outright. To size such a change from real data, pull the ad set's delivery yourself and pass it to the preview tool as delivery_records.

insights

• report -- Get performance metrics for the account or specific campaign.

  Required: account_id
  Optional: campaign_id, period (default: "last_7d"), level (default: "campaign")

  Period options: today, yesterday, last_7d, last_14d, last_30d, last_90d, this_month, last_month

  Level options: campaign, adset, ad

• breakdown -- Get performance broken down by demographic dimensions.

  Required: account_id, campaign_id
  Optional: breakdown (default: "age,gender"), period (default: "last_7d")

  Breakdown options: age, gender, age,gender, country, region, publisher_platform, platform_position, device_platform, impression_device

conversion definition (custom / non-standard events)

mureo counts conversions from the Insights actions array using a default deduped set of standard events (lead, purchase, complete_registration). If an advertiser's real conversion is a custom pixel event (offsite_conversion.custom.<id>, e.g. "Booking Completed"), or their account only emits a component row (offsite_conversion.fb_pixel_lead) with no generic aggregate, the default counts 0 for them — which silently wrong-foots CPA, daily-check, and budget decisions.

To fix, register the account's real conversion action_type(s):

1. Look up the account's actual labels — call meta_ads_insights_report (or _breakdown) and inspect the actions array's action_type values. Don't guess the string; custom slugs like offsite_conversion.custom.123 are easy to mistype.
2. Confirm with the operator which label(s) are their conversion.
3. Call mureo_state_set_conversion_events with platform="meta_ads", the account_id, and conversion_action_types=[…the exact string(s)…].

This is a replacement (the listed types become the complete conversion set for that account; never summed on top of the defaults). It is stored on platforms[meta_ads] in STATE.json and applied by every Meta conversion counter. Pass an empty list to clear it and restore the default.

The override is scoped to the account_id on that entry and applies only to it. If the entry carries no account_id (or an empty one — possible only in a hand-authored / externally written STATE.json), the override is ignored and the built-in generic set is used: an override belonging to an unidentifiable account must never redefine what counts as a conversion for a different one.

analysis

• performance -- Analyze overall performance trends.

  Required: account_id
  Optional: campaign_id, period

• audience -- Analyze audience performance and overlap.

  Required: account_id
  Optional: campaign_id, period

• placements -- Analyze placement performance breakdown.

  Required: account_id
  Optional: campaign_id, period

• cost -- Analyze cost trends and efficiency.

  Required: account_id
  Optional: campaign_id, period

• compare_ads -- Compare performance across ads.

  Required: account_id
  Optional: campaign_id, ad_set_id, period

• suggest_creative -- Suggest creative improvements based on data.

  Required: account_id
  Optional: campaign_id, period

audiences

• list -- List custom audiences in the ad account.

  Required: account_id
  Optional: limit (integer, default: 50)

• get -- Get audience details.

  Required: account_id, audience_id

• create -- Create a custom audience. Requires user confirmation.

  Required: account_id, name, subtype
  Optional: description, retention_days, pixel_id

  Subtype options: WEBSITE, CUSTOM, APP, ENGAGEMENT, OFFLINE
• delete -- Delete a custom audience. Requires user confirmation.

  Required: account_id, audience_id

• create_lookalike -- Create a lookalike audience. Requires user confirmation.

  Required: account_id, source_audience_id, country
  Optional: ratio (float, 0.01-0.20)

pixels

• list -- List pixels in the ad account.

  Required: account_id

• get -- Get pixel details.

  Required: account_id, pixel_id

• stats -- Get pixel firing statistics.

  Required: account_id, pixel_id

• events -- List pixel events.

  Required: account_id, pixel_id

conversions (CAPI)

• send -- Send conversion events (generic). Requires user confirmation.

  Required: account_id, pixel_id, events (array)

• send_purchase -- Send a purchase event. Requires user confirmation.

  Required: account_id, pixel_id, event_time, user_data, currency, value

• send_lead -- Send a lead event. Requires user confirmation.

  Required: account_id, pixel_id, event_time, user_data

creatives

• list -- List ad creatives.

  Required: account_id
  Optional: limit (integer, default: 50)

• create -- Create a standard ad creative (single image OR video). Requires user confirmation.

  Required: account_id, name, page_id, link_url
  Image mode: image_hash OR image_url (exactly one)
  Video mode: video_id + (video_thumbnail_image_hash OR video_thumbnail_image_url)
              + call_to_action (required in this mode)
  Optional: message, headline, description, call_to_action (image mode)

  Video and image parameters are mutually exclusive. Meta requires a thumbnail on every video creative, and the video must be fully processed first (see the Video creative flow below). call_to_action is mandatory in video mode: Meta's video_data has no link field, so the destination rides inside call_to_action.value.link. link_url is injected there automatically -- pass only the button label.
• create_dynamic -- Create a dynamic product ad creative. Requires user confirmation.

  Required: account_id, catalog_id
  Optional: product_set_id, message, link

• upload_image -- Upload an image for use in creatives.

  Required: account_id, file_path

• create_carousel -- Create a carousel creative (2-10 cards). Requires user confirmation.

  Required: account_id, page_id, cards (array), link

• create_collection -- Create a collection creative. Requires user confirmation.

  Required: account_id, page_id, product_ids (array), link

images

• upload_file -- Upload an image from local file.

  Required: account_id, file_path

catalogs (Product Catalog / DPA)

• list -- List product catalogs.

  Required: account_id, business_id

• get -- Get catalog details.

  Required: account_id, catalog_id

• create -- Create a product catalog. Requires user confirmation.

  Required: account_id, business_id, name

• delete -- Delete a product catalog. Requires user confirmation.

  Required: account_id, catalog_id

products

• list -- List products in a catalog.

  Required: account_id, catalog_id
  Optional: limit

• get -- Get product details.

  Required: account_id, product_id

• add -- Add a product to a catalog. Requires user confirmation.

  Required: account_id, catalog_id, retailer_id, name, availability, condition, price, url, image_url

• update -- Update a product. Requires user confirmation.

  Required: account_id, product_id
  Optional: name, availability, condition, price, url, image_url

• delete -- Delete a product. Requires user confirmation.

  Required: account_id, product_id

feeds

• list -- List feeds for a catalog.

  Required: account_id, catalog_id

• create -- Create a feed (URL-based, scheduled import). Requires user confirmation.

  Required: account_id, catalog_id, name, feed_url
  Optional: schedule (object)

lead_forms

• list -- List lead forms (per page).

  Required: account_id, page_id

• get -- Get lead form details.

  Required: account_id, form_id

• create -- Create a lead form. Requires user confirmation.

  Required: account_id, page_id, name, questions (array),
    privacy_policy_url, follow_up_action_url
  Optional advanced: locale, context_card (intro screen),
    thank_you_page (custom completion screen), is_higher_intent
    (3-step input→review→submit form), conditional_questions_choices
    (branching logic)

  follow_up_action_url is required by Meta — omitting it fails with error_subcode 1892085 / "Missing field(s): FollowUpActionURL". It is the URL behind the completion screen's button; thank_you_page adds a richer completion screen on top of it, it does not replace it.

  When to use is_higher_intent=true: trims junk submissions, lowers total volume — pick when CV quality matters more than CV volume (e.g. B2B / enterprise lead capture).

  When to use context_card: lifts conversion rate measurably. Always worth a {title, content, style=PARAGRAPH_STYLE} minimum for any campaign that survives past a 1-week test. cover_photo_id (a PAGE photo id picked from meta_ads_pages_photos_list) is write-only — Meta reads it back as context_card.cover_photo.id, so asking for context_card{cover_photo_id} returns a 400. Reusing an existing Page photo as a cover is undocumented by Meta: if the create call rejects the id, drop the cover or set it in Ads Manager — do not retry.

  When to use conditional_questions_choices: when a follow-up question is only relevant given a prior answer (e.g. "How many employees?" only if "Decision-maker?" was YES). Reduces form length for users who don't need the branch.

• update -- Change a lead form status (ACTIVE / ARCHIVED only — other fields are immutable post-creation). Requires user confirmation.

  Required: account_id, form_id, status ("ACTIVE" or "ARCHIVED")

• duplicate -- Copy an existing form (questions / privacy_policy / follow_up_action_url / locale / context_card / thank_you_page / is_higher_intent / conditional_questions_choices) under a new name on the given Page. The intro card's cover photo is re-mapped from the read shape (cover_photo.id) to the write shape (cover_photo_id). Fails fast when the source form has no privacy_policy.url or no follow_up_action_url — Meta requires both at creation time. Source form is untouched. Requires user confirmation.

  Required: account_id, form_id, page_id, new_name

leads

• export_csv -- Export form leads to a local CSV file. Header row is [id, created_time, *question_keys] (question_keys come from the form's declared questions in declared order, or from caller- supplied field_order to lock a custom schema). PII does NOT appear in mureo's log output — only the row count.

  Required: account_id, form_id, output_path
  Optional: limit (default 1000, max 1000), field_order (list of
    question keys to override column order)

• get -- Get lead data (per form).

  Required: account_id, form_id
  Optional: limit

• get_by_ad -- Get lead data (per ad).

  Required: account_id, ad_id
  Optional: limit

videos

Supported formats: MP4, MOV, AVI, WMV, MKV. Up to 1 GB per file through these tools; larger files need Meta's resumable (chunked) upload, which mureo does not implement yet.

• upload -- Upload a video from URL. Requires user confirmation.

  Required: account_id, video_url
  Optional: title

• upload_file -- Upload a video from local file. Requires user confirmation.

  Required: account_id, file_path
  Optional: title

• get -- Get video processing status / metadata.

  Required: account_id, video_id

  Returns status (nested: video_status, processing_phase), id, title, length, created_time. Poll until the video is ready -- a creative that references a still-processing video is rejected.
• thumbnails -- List auto-generated video thumbnails.

  Required: account_id, video_id

  Returns id, uri, is_preferred, height, width per thumbnail. Prefer the is_preferred entry and pass its uri as video_thumbnail_image_url to creatives_create. An empty list usually means the video is still processing.

Video creative flow

1. videos_upload / videos_upload_file -> video_id
2. videos_get -> poll until status.video_status reports ready (typically minutes; scales with file size and length)
3. videos_thumbnails -> pick a uri (prefer is_preferred: true)
4. creatives_create with video_id + video_thumbnail_image_url (or video_thumbnail_image_hash) + call_to_action (required in video mode -- it carries the destination link) -> creative_id
5. ads_create with that creative_id -- run the tracking-parameter pre-flight from ../_mureo-shared/SKILL.md first: the destination link lives on the creative (object_story_spec link, plus url_tags), so a copy-pasted creative carries the source campaign's tracking with it.

split_tests

• list -- List split tests.

  Required: account_id

• get -- Get split test details and results.

  Required: account_id, study_id

• create -- Create a split test. Requires user confirmation.

  Required: account_id, name, cells (array), objectives (array), start_time, end_time

• end -- End a split test. Requires user confirmation.

  Required: account_id, study_id

ad_rules

• list -- List automated rules.

  Required: account_id

• get -- Get rule details.

  Required: account_id, rule_id

• create -- Create an automated rule (alerts, auto-pause, etc.). Requires user confirmation.

  Required: account_id, name, evaluation_spec (object), execution_spec (object)

• update -- Update an automated rule. Requires user confirmation.

  Required: account_id, rule_id
  Optional: name, evaluation_spec, execution_spec, status

• delete -- Delete an automated rule. Requires user confirmation.

  Required: account_id, rule_id

page_posts

• list -- List Facebook page posts.

  Required: account_id, page_id
  Optional: limit

• boost -- Boost a page post (create ad from post). Requires user confirmation.

  Required: account_id, page_id, post_id, ad_set_id

instagram

• accounts -- List connected Instagram accounts.

  Required: account_id

• media -- List Instagram posts.

  Required: account_id, ig_user_id
  Optional: limit

• boost -- Boost an Instagram post (create ad from post). Requires user confirmation.

  Required: account_id, ig_user_id, media_id, ad_set_id

Common Workflows

1. Campaign Performance Check

Step 1: List active campaigns
  -> meta_ads_campaigns_list {account_id, status_filter: "ACTIVE"}

Step 2: Get performance report
  -> meta_ads_insights_report {account_id, period: "last_7d", level: "campaign"}

Step 3: Analyze performance trends
  -> meta_ads_analysis_performance {account_id}

Step 4: Break down by demographics
  -> meta_ads_insights_breakdown {account_id, campaign_id, breakdown: "age,gender"}

Step 5: Check placement performance
  -> meta_ads_analysis_placements {account_id}

2. Full Campaign Setup

Step 1: Create campaign (CONFIRM WITH USER)
  -> meta_ads_campaigns_create {account_id, name, objective, daily_budget}

Step 2: Create ad set with targeting (CONFIRM WITH USER)
  -> meta_ads_ad_sets_create {account_id, campaign_id, name, daily_budget, targeting}

Step 3: Upload image and create creative
  -> meta_ads_creatives_upload_image {account_id, image_url}
  -> meta_ads_creatives_create {account_id, name, image_hash, link_url, page_id}

Step 4: Create ad linking to creative (CONFIRM WITH USER)
  -> meta_ads_ads_create {account_id, ad_set_id, name, creative_id}

3. Audience & Lookalike Setup

Step 1: List existing audiences
  -> meta_ads_audiences_list {account_id}

Step 2: Create a website visitor audience (CONFIRM WITH USER)
  -> meta_ads_audiences_create {account_id, name, subtype: "WEBSITE", retention_days, pixel_id}

Step 3: Create a lookalike based on it (CONFIRM WITH USER)
  -> meta_ads_audiences_create_lookalike {account_id, source_audience_id, country: "JP"}

4. A/B Testing with Split Tests

Step 1: Create a split test (CONFIRM WITH USER)
  -> meta_ads_split_tests_create {account_id, name, cells, objectives, start_time, end_time}

Step 2: Monitor results
  -> meta_ads_split_tests_get {account_id, study_id}

Step 3: End the test when ready (CONFIRM WITH USER)
  -> meta_ads_split_tests_end {account_id, study_id}

5. Product Catalog & DPA

Step 1: Create a catalog (CONFIRM WITH USER)
  -> meta_ads_catalogs_create {account_id, business_id, name}

Step 2: Add products or create a feed
  -> meta_ads_products_add {account_id, catalog_id, retailer_id, name, ...}
  -> meta_ads_feeds_create {account_id, catalog_id, name, feed_url}

Step 3: Create a dynamic creative (multi-asset optimization) (CONFIRM WITH USER)
  -> meta_ads_creatives_create_dynamic {account_id, name, page_id, image_hashes, bodies, titles, link_url}

6. Lead Generation (Instant Form, end-to-end)

Step 1: Create the Instant Form (CONFIRM WITH USER)
  -> meta_ads_lead_forms_create {account_id, page_id, name, questions, privacy_policy_url, follow_up_action_url}
  Returns: { id: "<form_id>", ... }

Step 2: Create a Lead Ad creative attached to the form
  -> meta_ads_creatives_create_lead {
       account_id, name, page_id, form_id: "<form_id>",
       link_url: "<https-domain-verified-url>",
       image_hash (or image_url), message, headline,
       call_to_action: "SIGN_UP"   # default; APPLY_NOW / LEARN_MORE / etc. also valid
     }
  Returns: { id: "<creative_id>", ... }

Step 3: Set up the campaign + ad set
  -> meta_ads_campaigns_create {account_id, name, objective: "OUTCOME_LEADS"}
  -> meta_ads_ad_sets_create {
       account_id, campaign_id, name, daily_budget,
       optimization_goal: "LEAD_GENERATION",
       targeting: { ... }
     }

Step 4: Attach the creative to a new ad
  -> meta_ads_ads_create {account_id, ad_set_id, name, creative_id: "<creative_id>"}

Step 5: Download leads as they come in (poll)
  -> meta_ads_leads_get {account_id, form_id}
  Or by ad: meta_ads_leads_get_by_ad {account_id, ad_id}

The legacy LEAD_GENERATION campaign objective is still accepted by the API but OUTCOME_LEADS is the current (ODAX) canonical name.

Pre-requisites the API will enforce (catch them before campaign launch, not after):

• the Page that owns the form must have its lead-form Terms of Service accepted (or the form must be created with leadgen_tos_accepted=true);
• the Page must be linked to a CRM destination or have lead access configured, otherwise the lead data sits unread in Meta's UI.

7. Pause / Enable Entities

Pause a campaign:
  -> meta_ads_campaigns_pause {account_id, campaign_id}

Re-enable it:
  -> meta_ads_campaigns_enable {account_id, campaign_id}

Same pattern for ad_sets.pause/enable and ads.pause/enable.

8. Conversions API (Server-Side Tracking)

Step 1: List pixels and check events
  -> meta_ads_pixels_list {account_id}
  -> meta_ads_pixels_events {account_id, pixel_id}

Step 2: Send a purchase event (CONFIRM WITH USER)
  -> meta_ads_conversions_send_purchase {account_id, pixel_id, event_time, user_data, currency, value}

Important Notes

• Budget in cents: All budget and monetary values are in cents (1/100 of the account currency). For example, daily_budget: 500000 = 5,000 in the account currency.
• account_id format: Use the act_ form (a bare numeric id is prefixed), e.g. "act_123456789".
• Status values: Meta uses ACTIVE / PAUSED (not ENABLED).
• Creative-first model: In Meta Ads, you create a creative object first, then reference its creative_id when creating an ad.
• Targeting object: The targeting structure follows the Meta Marketing API format. Common fields include geo_locations, age_min, age_max, genders, interests, behaviors, and custom_audiences.
• Conversions API: Server-side events require hashed user_data (email, phone). The SDK handles hashing automatically.