Mureo Meta Ads

---
name: _mureo-meta-ads
description: "Meta Ads: Manage campaigns, ad sets, ads, insights, and audiences on Facebook/Instagram."
metadata:
  version: 0.21.3
  openclaw:
    category: "advertising"
    requires:
      bins:
        - mureo
    cliHelp: "mureo --help"
---

# Meta Ads (Marketing API v26.0)
> PREREQUISITE: Read `../_mureo-shared/SKILL.md` for auth, global flags, and security rules.

## Tool Summary

| # | Tool Name | Category | Type | Description |
|---|-----------|----------|------|-------------|
| 1 | `meta_ads_campaigns_list` | Campaign | Read | List campaigns |
| 2 | `meta_ads_campaigns_get` | Campaign | Read | Get campaign details |
| 3 | `meta_ads_campaigns_create` | Campaign | Write | Create a campaign |
| 4 | `meta_ads_campaigns_update` | Campaign | Write | Update campaign settings |
| 5 | `meta_ads_campaigns_pause` | Campaign | Write | Pause a campaign |
| 6 | `meta_ads_campaigns_enable` | Campaign | Write | Enable a paused campaign |
| 7 | `meta_ads_ad_sets_list` | Ad Set | Read | List ad sets |
| 8 | `meta_ads_ad_sets_get` | Ad Set | Read | Get ad set details |
| 9 | `meta_ads_ad_sets_create` | Ad Set | Write | Create an ad set |
| 10 | `meta_ads_ad_sets_update` | Ad Set | Write | Update ad set settings |
| 11 | `meta_ads_ad_sets_pause` | Ad Set | Write | Pause an ad set |
| 12 | `meta_ads_ad_sets_enable` | Ad Set | Write | Enable a paused ad set |
| 13 | `meta_ads_ads_list` | Ad | Read | List ads |
| 14 | `meta_ads_ads_get` | Ad | Read | Get ad details |
| 15 | `meta_ads_ads_create` | Ad | Write | Create an ad |
| 16 | `meta_ads_ads_update` | Ad | Write | Update an ad |
| 17 | `meta_ads_ads_pause` | Ad | Write | Pause an ad |
| 18 | `meta_ads_ads_enable` | Ad | Write | Enable a paused ad |
| 19 | `meta_ads_insights_report` | Insights | Read | Performance report |
| 20 | `meta_ads_insights_breakdown` | Insights | Read | Breakdown report (age, gender, etc.) |
| 21 | `meta_ads_analysis_performance` | Analysis | Read | Analyze overall performance trends |
| 22 | `meta_ads_analysis_audience` | Analysis | Read | Analyze audience performance and overlap |
| 23 | `meta_ads_analysis_placements` | Analysis | Read | Analyze placement performance breakdown |
| 24 | `meta_ads_analysis_cost` | Analysis | Read | Analyze cost trends and efficiency |
| 25 | `meta_ads_analysis_compare_ads` | Analysis | Read | Compare performance across ads |
| 26 | `meta_ads_analysis_suggest_creative` | Analysis | Read | Suggest creative improvements based on data |
| 27 | `meta_ads_audiences_list` | Audience | Read | List custom audiences |
| 28 | `meta_ads_audiences_get` | Audience | Read | Get audience details |
| 29 | `meta_ads_audiences_create` | Audience | Write | Create a custom audience |
| 30 | `meta_ads_audiences_delete` | Audience | Write | Delete a custom audience |
| 31 | `meta_ads_audiences_create_lookalike` | Audience | Write | Create a lookalike audience |
| 32 | `meta_ads_targeting_search` | Targeting | Read | Search targeting interests / behaviors by keyword |
| 33 | `meta_ads_targeting_categories` | Targeting | Read | List targeting category catalogues (behaviors, demographics, etc.) |
| 34 | `meta_ads_pixels_list` | Pixel | Read | List pixels |
| 35 | `meta_ads_pixels_get` | Pixel | Read | Get pixel details |
| 36 | `meta_ads_pixels_stats` | Pixel | Read | Get pixel firing statistics |
| 37 | `meta_ads_pixels_events` | Pixel | Read | List pixel events |
| 38 | `meta_ads_pixels_create` | Pixel | Write | Create a pixel |
| 39 | `meta_ads_conversions_send` | CAPI | Write | Send conversion events (generic) |
| 40 | `meta_ads_conversions_send_purchase` | CAPI | Write | Send a purchase event |
| 41 | `meta_ads_conversions_send_lead` | CAPI | Write | Send a lead event |
| 42 | `meta_ads_creatives_list` | Creative | Read | List ad creatives |
| 43 | `meta_ads_creatives_create` | Creative | Write | Create a standard ad creative (single image or video) |
| 44 | `meta_ads_creatives_create_dynamic` | Creative | Write | Create a dynamic product ad creative |
| 45 | `meta_ads_creatives_upload_image` | Creative | Write | Upload an image for use in creatives |
| 46 | `meta_ads_creatives_create_carousel` | Creative | Write | Create a carousel creative (2-10 cards) |
| 47 | `meta_ads_creatives_create_collection` | Creative | Write | Create a collection creative |
| 48 | `meta_ads_images_upload_file` | Image | Write | Upload an image from local file |
| 49 | `meta_ads_catalogs_list` | Catalog | Read | List product catalogs |
| 50 | `meta_ads_catalogs_get` | Catalog | Read | Get catalog details |
| 51 | `meta_ads_catalogs_create` | Catalog | Write | Create a product catalog |
| 52 | `meta_ads_catalogs_delete` | Catalog | Write | Delete a product catalog |
| 53 | `meta_ads_products_list` | Catalog | Read | List products in a catalog |
| 54 | `meta_ads_products_get` | Catalog | Read | Get product details |
| 55 | `meta_ads_products_add` | Catalog | Write | Add a product to a catalog |
| 56 | `meta_ads_products_update` | Catalog | Write | Update a product |
| 57 | `meta_ads_products_delete` | Catalog | Write | Delete a product |
| 58 | `meta_ads_feeds_list` | Catalog | Read | List feeds for a catalog |
| 59 | `meta_ads_feeds_create` | Catalog | Write | Create a feed (URL-based, scheduled import) |
| 60 | `meta_ads_lead_forms_list` | Lead | Read | List lead forms (per page) |
| 61 | `meta_ads_lead_forms_get` | Lead | Read | Get lead form details |
| 62 | `meta_ads_lead_forms_create` | Lead | Write | Create a lead form |
| 63 | `meta_ads_leads_get` | Lead | Read | Get lead data (per form) |
| 64 | `meta_ads_leads_get_by_ad` | Lead | Read | Get lead data (per ad) |
| 65 | `meta_ads_videos_upload` | Video | Write | Upload a video from URL |
| 66 | `meta_ads_videos_upload_file` | Video | Write | Upload a video from local file |
| 67 | `meta_ads_split_tests_list` | Split Test | Read | List split tests |
| 68 | `meta_ads_split_tests_get` | Split Test | Read | Get split test details and results |
| 69 | `meta_ads_split_tests_create` | Split Test | Write | Create a split test |
| 70 | `meta_ads_split_tests_end` | Split Test | Write | End a split test |
| 71 | `meta_ads_ad_rules_list` | Ad Rule | Read | List automated rules |
| 72 | `meta_ads_ad_rules_get` | Ad Rule | Read | Get rule details |
| 73 | `meta_ads_ad_rules_create` | Ad Rule | Write | Create an automated rule |
| 74 | `meta_ads_ad_rules_update` | Ad Rule | Write | Update an automated rule |
| 75 | `meta_ads_ad_rules_delete` | Ad Rule | Write | Delete an automated rule |
| 76 | `meta_ads_page_posts_list` | Page Post | Read | List Facebook page posts |
| 77 | `meta_ads_page_posts_boost` | Page Post | Write | Boost a page post (create ad from post) |
| 78 | `meta_ads_instagram_accounts` | Instagram | Read | List connected Instagram accounts |
| 79 | `meta_ads_instagram_media` | Instagram | Read | List Instagram posts |
| 80 | `meta_ads_instagram_boost` | Instagram | Write | Boost an Instagram post |
| 81 | `meta_ads_pages_list` | Page | Read | List manageable Facebook Pages (personal + business-owned) |
| 82 | `meta_ads_pages_photos_list` | Page | Read | List a Page's existing photos (pick a Page photo id) |
| 83 | `meta_ads_creatives_create_lead` | Lead / Creative | Write | Create a Lead Ad AdCreative attached to an Instant Form |
| 84 | `meta_ads_lead_forms_update` | Lead | Write | Change a lead form status (ACTIVE / ARCHIVED) |
| 85 | `meta_ads_lead_forms_duplicate` | Lead | Write | Duplicate a lead form under a Page with a new name |
| 86 | `meta_ads_leads_export_csv` | Lead | Write (local) | Export form leads to a local CSV file |
| 87 | `meta_ads_videos_get` | Video | Read | Get video processing status / metadata |
| 88 | `meta_ads_videos_thumbnails` | Video | Read | List auto-generated video thumbnails |
| 89 | `meta_ads_excluded_placements_get` | Placement Exclusion | Read | Read an ad set's publisher / app-category / brand-safety exclusions |
| 90 | `meta_ads_excluded_placements_set` | Placement Exclusion | Write | Replace the supplied exclusion facets on an ad set |

## Key Differences from Google Ads

| Aspect | Google Ads | Meta Ads |
|--------|-----------|----------|
| Account ID format | `"1234567890"` | `"act_XXXXXXXXXXXX"` |
| Budget unit | Currency amount | Cents (1/100 of currency unit) |
| Hierarchy | Campaign > Ad Group > Ad | Campaign > Ad Set > Ad |
| Ad creation | Inline headlines/descriptions | Separate creative, then link to ad |
| Status values | `ENABLED` / `PAUSED` / `REMOVED` | `ACTIVE` / `PAUSED` |
| Period format | `LAST_7_DAYS` | `last_7d` |

## 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**: Must include the `act_` prefix (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.