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
| # |
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):
- 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.
- Confirm with the operator which label(s) are their conversion.
- 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
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
videos_upload / videos_upload_file -> video_id
videos_get -> poll until status.video_status reports ready
(typically minutes; scales with file size and length)
videos_thumbnails -> pick a uri (prefer is_preferred: true)
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
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.
1---2name: mureo-meta-ads3description: "Meta Ads: Manage campaigns, ad sets, ads, insights, and audiences on Facebook/Instagram."4metadata:5 source: https://skillmd.com/skills/majiayu000/mureo-meta-ads6 version: 0.39.07 openclaw:8 category: "advertising"9 requires:10 bins:11 - mureo12 cliHelp: "mureo --help"13---1415# Meta Ads (Marketing API v26.0)16> PREREQUISITE: Read `../_mureo-shared/SKILL.md` for auth, global flags, and security rules.1718> 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.1920## Tool Summary2122| # | Tool Name | Category | Type | Description |23|---|-----------|----------|------|-------------|24| 1 | `meta_ads_campaigns_list` | Campaign | Read | List campaigns |25| 2 | `meta_ads_campaigns_get` | Campaign | Read | Get campaign details |26| 3 | `meta_ads_campaigns_create` | Campaign | Write | Create a campaign |27| 4 | `meta_ads_campaigns_update` | Campaign | Write | Update campaign settings |28| 5 | `meta_ads_campaigns_pause` | Campaign | Write | Pause a campaign |29| 6 | `meta_ads_campaigns_enable` | Campaign | Write | Enable a paused campaign |30| 7 | `meta_ads_ad_sets_list` | Ad Set | Read | List ad sets |31| 8 | `meta_ads_ad_sets_get` | Ad Set | Read | Get ad set details |32| 9 | `meta_ads_ad_sets_create` | Ad Set | Write | Create an ad set |33| 10 | `meta_ads_ad_sets_update` | Ad Set | Write | Update ad set settings |34| 11 | `meta_ads_ad_sets_pause` | Ad Set | Write | Pause an ad set |35| 12 | `meta_ads_ad_sets_enable` | Ad Set | Write | Enable a paused ad set |36| 13 | `meta_ads_ads_list` | Ad | Read | List ads |37| 14 | `meta_ads_ads_get` | Ad | Read | Get ad details |38| 15 | `meta_ads_ads_create` | Ad | Write | Create an ad |39| 16 | `meta_ads_ads_update` | Ad | Write | Update an ad |40| 17 | `meta_ads_ads_pause` | Ad | Write | Pause an ad |41| 18 | `meta_ads_ads_enable` | Ad | Write | Enable a paused ad |42| 19 | `meta_ads_insights_report` | Insights | Read | Performance report |43| 20 | `meta_ads_insights_breakdown` | Insights | Read | Breakdown report (age, gender, etc.) |44| 21 | `meta_ads_analysis_performance` | Analysis | Read | Analyze overall performance trends |45| 22 | `meta_ads_analysis_audience` | Analysis | Read | Analyze audience performance and overlap |46| 23 | `meta_ads_analysis_placements` | Analysis | Read | Analyze placement performance breakdown |47| 24 | `meta_ads_analysis_cost` | Analysis | Read | Analyze cost trends and efficiency |48| 25 | `meta_ads_analysis_compare_ads` | Analysis | Read | Compare performance across ads |49| 26 | `meta_ads_analysis_suggest_creative` | Analysis | Read | Suggest creative improvements based on data |50| 27 | `meta_ads_audiences_list` | Audience | Read | List custom audiences |51| 28 | `meta_ads_audiences_get` | Audience | Read | Get audience details |52| 29 | `meta_ads_audiences_create` | Audience | Write | Create a custom audience |53| 30 | `meta_ads_audiences_delete` | Audience | Write | Delete a custom audience |54| 31 | `meta_ads_audiences_create_lookalike` | Audience | Write | Create a lookalike audience |55| 32 | `meta_ads_targeting_search` | Targeting | Read | Search targeting interests / behaviors by keyword |56| 33 | `meta_ads_targeting_categories` | Targeting | Read | List targeting category catalogues (behaviors, demographics, etc.) |57| 34 | `meta_ads_pixels_list` | Pixel | Read | List pixels |58| 35 | `meta_ads_pixels_get` | Pixel | Read | Get pixel details |59| 36 | `meta_ads_pixels_stats` | Pixel | Read | Get pixel firing statistics |60| 37 | `meta_ads_pixels_events` | Pixel | Read | List pixel events |61| 38 | `meta_ads_pixels_create` | Pixel | Write | Create a pixel |62| 39 | `meta_ads_conversions_send` | CAPI | Write | Send conversion events (generic) |63| 40 | `meta_ads_conversions_send_purchase` | CAPI | Write | Send a purchase event |64| 41 | `meta_ads_conversions_send_lead` | CAPI | Write | Send a lead event |65| 42 | `meta_ads_creatives_list` | Creative | Read | List ad creatives |66| 43 | `meta_ads_creatives_create` | Creative | Write | Create a standard ad creative (single image or video) |67| 44 | `meta_ads_creatives_create_dynamic` | Creative | Write | Create a dynamic product ad creative |68| 45 | `meta_ads_creatives_upload_image` | Creative | Write | Upload an image for use in creatives |69| 46 | `meta_ads_creatives_create_carousel` | Creative | Write | Create a carousel creative (2-10 cards) |70| 47 | `meta_ads_creatives_create_collection` | Creative | Write | Create a collection creative |71| 48 | `meta_ads_images_upload_file` | Image | Write | Upload an image from local file |72| 49 | `meta_ads_catalogs_list` | Catalog | Read | List product catalogs |73| 50 | `meta_ads_catalogs_get` | Catalog | Read | Get catalog details |74| 51 | `meta_ads_catalogs_create` | Catalog | Write | Create a product catalog |75| 52 | `meta_ads_catalogs_delete` | Catalog | Write | Delete a product catalog |76| 53 | `meta_ads_products_list` | Catalog | Read | List products in a catalog |77| 54 | `meta_ads_products_get` | Catalog | Read | Get product details |78| 55 | `meta_ads_products_add` | Catalog | Write | Add a product to a catalog |79| 56 | `meta_ads_products_update` | Catalog | Write | Update a product |80| 57 | `meta_ads_products_delete` | Catalog | Write | Delete a product |81| 58 | `meta_ads_feeds_list` | Catalog | Read | List feeds for a catalog |82| 59 | `meta_ads_feeds_create` | Catalog | Write | Create a feed (URL-based, scheduled import) |83| 60 | `meta_ads_lead_forms_list` | Lead | Read | List lead forms (per page) |84| 61 | `meta_ads_lead_forms_get` | Lead | Read | Get lead form details |85| 62 | `meta_ads_lead_forms_create` | Lead | Write | Create a lead form |86| 63 | `meta_ads_leads_get` | Lead | Read | Get lead data (per form) |87| 64 | `meta_ads_leads_get_by_ad` | Lead | Read | Get lead data (per ad) |88| 65 | `meta_ads_videos_upload` | Video | Write | Upload a video from URL |89| 66 | `meta_ads_videos_upload_file` | Video | Write | Upload a video from local file |90| 67 | `meta_ads_split_tests_list` | Split Test | Read | List split tests |91| 68 | `meta_ads_split_tests_get` | Split Test | Read | Get split test details and results |92| 69 | `meta_ads_split_tests_create` | Split Test | Write | Create a split test |93| 70 | `meta_ads_split_tests_end` | Split Test | Write | End a split test |94| 71 | `meta_ads_ad_rules_list` | Ad Rule | Read | List automated rules |95| 72 | `meta_ads_ad_rules_get` | Ad Rule | Read | Get rule details |96| 73 | `meta_ads_ad_rules_create` | Ad Rule | Write | Create an automated rule |97| 74 | `meta_ads_ad_rules_update` | Ad Rule | Write | Update an automated rule |98| 75 | `meta_ads_ad_rules_delete` | Ad Rule | Write | Delete an automated rule |99| 76 | `meta_ads_page_posts_list` | Page Post | Read | List Facebook page posts |100| 77 | `meta_ads_page_posts_boost` | Page Post | Write | Boost a page post (create ad from post) |101| 78 | `meta_ads_instagram_accounts` | Instagram | Read | List connected Instagram accounts |102| 79 | `meta_ads_instagram_media` | Instagram | Read | List Instagram posts |103| 80 | `meta_ads_instagram_boost` | Instagram | Write | Boost an Instagram post |104| 81 | `meta_ads_pages_list` | Page | Read | List manageable Facebook Pages (personal + business-owned) |105| 82 | `meta_ads_pages_photos_list` | Page | Read | List a Page's existing photos (pick a Page photo id) |106| 83 | `meta_ads_creatives_create_lead` | Lead / Creative | Write | Create a Lead Ad AdCreative attached to an Instant Form |107| 84 | `meta_ads_lead_forms_update` | Lead | Write | Change a lead form status (ACTIVE / ARCHIVED) |108| 85 | `meta_ads_lead_forms_duplicate` | Lead | Write | Duplicate a lead form under a Page with a new name |109| 86 | `meta_ads_leads_export_csv` | Lead | Write (local) | Export form leads to a local CSV file |110| 87 | `meta_ads_videos_get` | Video | Read | Get video processing status / metadata |111| 88 | `meta_ads_videos_thumbnails` | Video | Read | List auto-generated video thumbnails |112| 89 | `meta_ads_excluded_placements_get` | Placement Exclusion | Read | Read an ad set's publisher / app-category / brand-safety exclusions |113| 90 | `meta_ads_excluded_placements_set` | Placement Exclusion | Write | Replace the supplied exclusion facets on an ad set |114115## Key Differences from Google Ads116117| Aspect | Google Ads | Meta Ads |118|--------|-----------|----------|119| Account ID format | `"1234567890"` | `"act_XXXXXXXXXXXX"` |120| Budget unit | Currency amount | Cents (1/100 of currency unit) |121| Hierarchy | Campaign > Ad Group > Ad | Campaign > Ad Set > Ad |122| Ad creation | Inline headlines/descriptions | Separate creative, then link to ad |123| Status values | `ENABLED` / `PAUSED` / `REMOVED` | `ACTIVE` / `PAUSED` |124| Period format | `LAST_7_DAYS` | `last_7d` |125126## API Resources127128### campaigns129130- `list` -- List all campaigns in the ad account.131 ```132 Required: account_id (string, "act_XXXX" format)133 Optional: status_filter (string: "ACTIVE" | "PAUSED"), limit (integer, default: 50)134 ```135136- `get` -- Get detailed information about a specific campaign.137 ```138 Required: account_id, campaign_id139 ```140141- `create` -- Create a new campaign. **Requires user confirmation.**142 ```143 Required: account_id, name, objective144 Optional: status (default: "PAUSED"), daily_budget (integer, in cents), lifetime_budget (integer, in cents)145 ```146 Objective options: `CONVERSIONS`, `LINK_CLICKS`, `REACH`, `BRAND_AWARENESS`, `VIDEO_VIEWS`, `LEAD_GENERATION`, `MESSAGES`, `APP_INSTALLS`147148- `update` -- Update campaign settings. **Requires user confirmation.**149 ```150 Required: account_id, campaign_id151 Optional: name, status, daily_budget (integer, in cents)152 ```153154- `pause` -- Pause a campaign. **Requires user confirmation.**155 ```156 Required: account_id, campaign_id157 ```158159- `enable` -- Enable a paused campaign. **Requires user confirmation.**160 ```161 Required: account_id, campaign_id162 ```163164### ad_sets165166- `list` -- List ad sets, optionally filtered by campaign.167 ```168 Required: account_id169 Optional: campaign_id, limit (integer, default: 50)170 ```171172- `get` -- Get ad set details.173 ```174 Required: account_id, ad_set_id175 ```176177- `create` -- Create an ad set with targeting and budget. **Requires user confirmation.**178 ```179 Required: account_id, campaign_id, name, daily_budget (integer, in cents)180 Optional: billing_event (default: "IMPRESSIONS"), optimization_goal (default: "REACH"),181 targeting (object), status (default: "PAUSED")182 ```183 Optimization goals: `REACH`, `IMPRESSIONS`, `OFFSITE_CONVERSIONS`, `LINK_CLICKS`, `LANDING_PAGE_VIEWS`, `LEAD_GENERATION`, `VALUE`184185 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`.186187- `update` -- Update ad set settings. **Requires user confirmation.**188 ```189 Required: account_id, ad_set_id190 Optional: name, status, daily_budget (integer, in cents), targeting (object)191 ```192193- `pause` -- Pause an ad set. **Requires user confirmation.**194 ```195 Required: account_id, ad_set_id196 ```197198- `enable` -- Enable a paused ad set. **Requires user confirmation.**199 ```200 Required: account_id, ad_set_id201 ```202203### ads204205- `list` -- List ads, optionally filtered by ad set.206 ```207 Required: account_id208 Optional: ad_set_id, limit (integer, default: 50)209 ```210211- `get` -- Get ad details.212 ```213 Required: account_id, ad_id214 ```215216- `create` -- Create an ad linking to an existing creative. **Requires user confirmation.**217 ```218 Required: account_id, ad_set_id, name, creative_id219 Optional: status (default: "PAUSED")220 ```221222- `update` -- Update ad name or status. **Requires user confirmation.**223 ```224 Required: account_id, ad_id225 Optional: name, status ("ACTIVE" | "PAUSED")226 ```227228- `pause` -- Pause an ad. **Requires user confirmation.**229 ```230 Required: account_id, ad_id231 ```232233- `enable` -- Enable a paused ad. **Requires user confirmation.**234 ```235 Required: account_id, ad_id236 ```237238### excluded_placements239240Delivery-surface exclusions: which publishers, Audience Network app categories and content241types an ad set must **not** be delivered against. Meta stores these inside the ad set's242`targeting` spec, but they get their own tools so mureo can record the change with an243`observation_due` window and reverse it — a generic `ad_sets.update` targeting write is244indistinguishable from any other targeting edit.245246- `get` -- Read the ad set's current exclusion lists. Always returns all three keys; an247 unset facet reads as an empty array.248 ```249 Required: account_id, ad_set_id250 ```251252- `set` -- Replace the supplied exclusion facets. **Requires user confirmation.** Each253 supplied facet REPLACES its current value (Meta has no append here) — call `get` first and254 send the full intended set. An omitted facet is left untouched; an empty array clears it.255 The rest of the targeting spec is preserved by a read-modify-write merge.256 ```257 Required: account_id, ad_set_id258 Optional: excluded_publisher_categories, excluded_publisher_list_ids,259 excluded_brand_safety_content_types (arrays of string; at least one required)260 ```261262 **Delivery impact is not measurable here, and mureo says so (#547).** None of Meta's263 insights breakdowns attribute past delivery to publisher categories, publisher block264 lists or brand-safety content types — `publisher_platform` / `platform_position` are a265 different exclusion surface (ad-set targeting). So266 `analysis_exclusion_impact_preview` reports `coverage: "unknown"` for this tool, never267 "no impact", and the call's own result carries the same verdict. Tell the operator the268 size is unknown rather than implying it is small. An operator who would rather refuse269 than proceed blind sets `block_exclusions_without_impact_data: true` in STRATEGY.md270 `## Guardrails`, which refuses this tool outright. To size such a change from real271 data, pull the ad set's delivery yourself and pass it to the preview tool as272 `delivery_records`.273274### insights275276- `report` -- Get performance metrics for the account or specific campaign.277 ```278 Required: account_id279 Optional: campaign_id, period (default: "last_7d"), level (default: "campaign")280 ```281 Period options: `today`, `yesterday`, `last_7d`, `last_14d`, `last_30d`, `last_90d`, `this_month`, `last_month`282283 Level options: `campaign`, `adset`, `ad`284285- `breakdown` -- Get performance broken down by demographic dimensions.286 ```287 Required: account_id, campaign_id288 Optional: breakdown (default: "age,gender"), period (default: "last_7d")289 ```290 Breakdown options: `age`, `gender`, `age,gender`, `country`, `region`, `publisher_platform`, `platform_position`, `device_platform`, `impression_device`291292### conversion definition (custom / non-standard events)293294mureo counts conversions from the Insights `actions` array using a **default295deduped set of standard events** (`lead`, `purchase`, `complete_registration`).296If an advertiser's real conversion is a **custom pixel event**297(`offsite_conversion.custom.<id>`, e.g. "Booking Completed"), or their account298only emits a component row (`offsite_conversion.fb_pixel_lead`) with no generic299aggregate, the default counts **0** for them — which silently wrong-foots CPA,300daily-check, and budget decisions.301302To fix, register the account's real conversion `action_type`(s):3033041. Look up the account's **actual** labels — call `meta_ads_insights_report`305 (or `_breakdown`) and inspect the `actions` array's `action_type` values.306 Don't guess the string; custom slugs like `offsite_conversion.custom.123`307 are easy to mistype.3082. Confirm with the operator which label(s) are *their* conversion.3093. Call **`mureo_state_set_conversion_events`** with `platform="meta_ads"`,310 the `account_id`, and `conversion_action_types=[…the exact string(s)…]`.311312This is a **replacement** (the listed types become the complete conversion set313for that account; never summed on top of the defaults). It is stored on314`platforms[meta_ads]` in STATE.json and applied by every Meta conversion315counter. Pass an empty list to clear it and restore the default.316317The override is **scoped to the `account_id` on that entry** and applies only318to it. If the entry carries no `account_id` (or an empty one — possible only in319a hand-authored / externally written STATE.json), the override is **ignored**320and the built-in generic set is used: an override belonging to an321unidentifiable account must never redefine what counts as a conversion for a322different one.323324### analysis325326- `performance` -- Analyze overall performance trends.327 ```328 Required: account_id329 Optional: campaign_id, period330 ```331332- `audience` -- Analyze audience performance and overlap.333 ```334 Required: account_id335 Optional: campaign_id, period336 ```337338- `placements` -- Analyze placement performance breakdown.339 ```340 Required: account_id341 Optional: campaign_id, period342 ```343344- `cost` -- Analyze cost trends and efficiency.345 ```346 Required: account_id347 Optional: campaign_id, period348 ```349350- `compare_ads` -- Compare performance across ads.351 ```352 Required: account_id353 Optional: campaign_id, ad_set_id, period354 ```355356- `suggest_creative` -- Suggest creative improvements based on data.357 ```358 Required: account_id359 Optional: campaign_id, period360 ```361362### audiences363364- `list` -- List custom audiences in the ad account.365 ```366 Required: account_id367 Optional: limit (integer, default: 50)368 ```369370- `get` -- Get audience details.371 ```372 Required: account_id, audience_id373 ```374375- `create` -- Create a custom audience. **Requires user confirmation.**376 ```377 Required: account_id, name, subtype378 Optional: description, retention_days, pixel_id379 ```380 Subtype options: `WEBSITE`, `CUSTOM`, `APP`, `ENGAGEMENT`, `OFFLINE`381382- `delete` -- Delete a custom audience. **Requires user confirmation.**383 ```384 Required: account_id, audience_id385 ```386387- `create_lookalike` -- Create a lookalike audience. **Requires user confirmation.**388 ```389 Required: account_id, source_audience_id, country390 Optional: ratio (float, 0.01-0.20)391 ```392393### pixels394395- `list` -- List pixels in the ad account.396 ```397 Required: account_id398 ```399400- `get` -- Get pixel details.401 ```402 Required: account_id, pixel_id403 ```404405- `stats` -- Get pixel firing statistics.406 ```407 Required: account_id, pixel_id408 ```409410- `events` -- List pixel events.411 ```412 Required: account_id, pixel_id413 ```414415### conversions (CAPI)416417- `send` -- Send conversion events (generic). **Requires user confirmation.**418 ```419 Required: account_id, pixel_id, events (array)420 ```421422- `send_purchase` -- Send a purchase event. **Requires user confirmation.**423 ```424 Required: account_id, pixel_id, event_time, user_data, currency, value425 ```426427- `send_lead` -- Send a lead event. **Requires user confirmation.**428 ```429 Required: account_id, pixel_id, event_time, user_data430 ```431432### creatives433434- `list` -- List ad creatives.435 ```436 Required: account_id437 Optional: limit (integer, default: 50)438 ```439440- `create` -- Create a standard ad creative (single image OR video). **Requires user confirmation.**441 ```442 Required: account_id, name, page_id, link_url443 Image mode: image_hash OR image_url (exactly one)444 Video mode: video_id + (video_thumbnail_image_hash OR video_thumbnail_image_url)445 + call_to_action (required in this mode)446 Optional: message, headline, description, call_to_action (image mode)447 ```448 Video and image parameters are mutually exclusive. Meta requires a449 thumbnail on every video creative, and the video must be fully450 processed first (see the Video creative flow below). `call_to_action`451 is mandatory in video mode: Meta's `video_data` has no `link` field, so452 the destination rides inside `call_to_action.value.link`. `link_url` is453 injected there automatically -- pass only the button label.454455- `create_dynamic` -- Create a dynamic product ad creative. **Requires user confirmation.**456 ```457 Required: account_id, catalog_id458 Optional: product_set_id, message, link459 ```460461- `upload_image` -- Upload an image for use in creatives.462 ```463 Required: account_id, file_path464 ```465466- `create_carousel` -- Create a carousel creative (2-10 cards). **Requires user confirmation.**467 ```468 Required: account_id, page_id, cards (array), link469 ```470471- `create_collection` -- Create a collection creative. **Requires user confirmation.**472 ```473 Required: account_id, page_id, product_ids (array), link474 ```475476### images477478- `upload_file` -- Upload an image from local file.479 ```480 Required: account_id, file_path481 ```482483### catalogs (Product Catalog / DPA)484485- `list` -- List product catalogs.486 ```487 Required: account_id, business_id488 ```489490- `get` -- Get catalog details.491 ```492 Required: account_id, catalog_id493 ```494495- `create` -- Create a product catalog. **Requires user confirmation.**496 ```497 Required: account_id, business_id, name498 ```499500- `delete` -- Delete a product catalog. **Requires user confirmation.**501 ```502 Required: account_id, catalog_id503 ```504505### products506507- `list` -- List products in a catalog.508 ```509 Required: account_id, catalog_id510 Optional: limit511 ```512513- `get` -- Get product details.514 ```515 Required: account_id, product_id516 ```517518- `add` -- Add a product to a catalog. **Requires user confirmation.**519 ```520 Required: account_id, catalog_id, retailer_id, name, availability, condition, price, url, image_url521 ```522523- `update` -- Update a product. **Requires user confirmation.**524 ```525 Required: account_id, product_id526 Optional: name, availability, condition, price, url, image_url527 ```528529- `delete` -- Delete a product. **Requires user confirmation.**530 ```531 Required: account_id, product_id532 ```533534### feeds535536- `list` -- List feeds for a catalog.537 ```538 Required: account_id, catalog_id539 ```540541- `create` -- Create a feed (URL-based, scheduled import). **Requires user confirmation.**542 ```543 Required: account_id, catalog_id, name, feed_url544 Optional: schedule (object)545 ```546547### lead_forms548549- `list` -- List lead forms (per page).550 ```551 Required: account_id, page_id552 ```553554- `get` -- Get lead form details.555 ```556 Required: account_id, form_id557 ```558559- `create` -- Create a lead form. **Requires user confirmation.**560 ```561 Required: account_id, page_id, name, questions (array),562 privacy_policy_url, follow_up_action_url563 Optional advanced: locale, context_card (intro screen),564 thank_you_page (custom completion screen), is_higher_intent565 (3-step input→review→submit form), conditional_questions_choices566 (branching logic)567 ```568569 `follow_up_action_url` is required by Meta — omitting it fails with570 `error_subcode 1892085` / "Missing field(s): FollowUpActionURL". It is571 the URL behind the completion screen's button; `thank_you_page` adds a572 richer completion screen on top of it, it does not replace it.573574 When to use `is_higher_intent=true`: trims junk submissions, lowers575 total volume — pick when CV quality matters more than CV volume576 (e.g. B2B / enterprise lead capture).577578 When to use `context_card`: lifts conversion rate measurably. Always579 worth a `{title, content, style=PARAGRAPH_STYLE}` minimum for any580 campaign that survives past a 1-week test. `cover_photo_id` (a PAGE581 photo id picked from `meta_ads_pages_photos_list`) is write-only — Meta582 reads it back as `context_card.cover_photo.id`, so asking for583 `context_card{cover_photo_id}` returns a 400. Reusing an existing Page584 photo as a cover is undocumented by Meta: if the create call rejects585 the id, drop the cover or set it in Ads Manager — do not retry.586587 When to use `conditional_questions_choices`: when a follow-up588 question is only relevant given a prior answer (e.g. "How many589 employees?" only if "Decision-maker?" was YES). Reduces form length590 for users who don't need the branch.591592- `update` -- Change a lead form status (ACTIVE / ARCHIVED only — other593 fields are immutable post-creation). **Requires user confirmation.**594 ```595 Required: account_id, form_id, status ("ACTIVE" or "ARCHIVED")596 ```597598- `duplicate` -- Copy an existing form (questions / privacy_policy /599 follow_up_action_url / locale / context_card / thank_you_page /600 is_higher_intent / conditional_questions_choices) under a new name on601 the given Page. The intro card's cover photo is re-mapped from the602 read shape (`cover_photo.id`) to the write shape (`cover_photo_id`).603 Fails fast when the source form has no `privacy_policy.url` or no604 `follow_up_action_url` — Meta requires both at creation time.605 Source form is untouched. **Requires user confirmation.**606 ```607 Required: account_id, form_id, page_id, new_name608 ```609610### leads611612- `export_csv` -- Export form leads to a local CSV file. Header row613 is ``[id, created_time, *question_keys]`` (question_keys come from614 the form's declared questions in declared order, or from caller-615 supplied ``field_order`` to lock a custom schema). PII does NOT616 appear in mureo's log output — only the row count.617 ```618 Required: account_id, form_id, output_path619 Optional: limit (default 1000, max 1000), field_order (list of620 question keys to override column order)621 ```622623- `get` -- Get lead data (per form).624 ```625 Required: account_id, form_id626 Optional: limit627 ```628629- `get_by_ad` -- Get lead data (per ad).630 ```631 Required: account_id, ad_id632 Optional: limit633 ```634635### videos636637Supported formats: MP4, MOV, AVI, WMV, MKV. Up to 1 GB per file through638these tools; larger files need Meta's resumable (chunked) upload, which639mureo does not implement yet.640641- `upload` -- Upload a video from URL. **Requires user confirmation.**642 ```643 Required: account_id, video_url644 Optional: title645 ```646647- `upload_file` -- Upload a video from local file. **Requires user confirmation.**648 ```649 Required: account_id, file_path650 Optional: title651 ```652653- `get` -- Get video processing status / metadata.654 ```655 Required: account_id, video_id656 ```657 Returns `status` (nested: `video_status`, `processing_phase`), `id`,658 `title`, `length`, `created_time`. Poll until the video is ready --659 a creative that references a still-processing video is rejected.660661- `thumbnails` -- List auto-generated video thumbnails.662 ```663 Required: account_id, video_id664 ```665 Returns `id`, `uri`, `is_preferred`, `height`, `width` per thumbnail.666 Prefer the `is_preferred` entry and pass its `uri` as667 `video_thumbnail_image_url` to `creatives_create`. An empty list668 usually means the video is still processing.669670#### Video creative flow6716721. `videos_upload` / `videos_upload_file` -> `video_id`6732. `videos_get` -> poll until `status.video_status` reports ready674 (typically minutes; scales with file size and length)6753. `videos_thumbnails` -> pick a `uri` (prefer `is_preferred: true`)6764. `creatives_create` with `video_id` + `video_thumbnail_image_url`677 (or `video_thumbnail_image_hash`) + `call_to_action` (required in678 video mode -- it carries the destination link) -> `creative_id`6795. `ads_create` with that `creative_id` -- run the tracking-parameter680 pre-flight from `../_mureo-shared/SKILL.md` first: the destination link681 lives on the creative (`object_story_spec` link, plus `url_tags`), so a682 copy-pasted creative carries the source campaign's tracking with it.683684### split_tests685686- `list` -- List split tests.687 ```688 Required: account_id689 ```690691- `get` -- Get split test details and results.692 ```693 Required: account_id, study_id694 ```695696- `create` -- Create a split test. **Requires user confirmation.**697 ```698 Required: account_id, name, cells (array), objectives (array), start_time, end_time699 ```700701- `end` -- End a split test. **Requires user confirmation.**702 ```703 Required: account_id, study_id704 ```705706### ad_rules707708- `list` -- List automated rules.709 ```710 Required: account_id711 ```712713- `get` -- Get rule details.714 ```715 Required: account_id, rule_id716 ```717718- `create` -- Create an automated rule (alerts, auto-pause, etc.). **Requires user confirmation.**719 ```720 Required: account_id, name, evaluation_spec (object), execution_spec (object)721 ```722723- `update` -- Update an automated rule. **Requires user confirmation.**724 ```725 Required: account_id, rule_id726 Optional: name, evaluation_spec, execution_spec, status727 ```728729- `delete` -- Delete an automated rule. **Requires user confirmation.**730 ```731 Required: account_id, rule_id732 ```733734### page_posts735736- `list` -- List Facebook page posts.737 ```738 Required: account_id, page_id739 Optional: limit740 ```741742- `boost` -- Boost a page post (create ad from post). **Requires user confirmation.**743 ```744 Required: account_id, page_id, post_id, ad_set_id745 ```746747### instagram748749- `accounts` -- List connected Instagram accounts.750 ```751 Required: account_id752 ```753754- `media` -- List Instagram posts.755 ```756 Required: account_id, ig_user_id757 Optional: limit758 ```759760- `boost` -- Boost an Instagram post (create ad from post). **Requires user confirmation.**761 ```762 Required: account_id, ig_user_id, media_id, ad_set_id763 ```764765## Common Workflows766767### 1. Campaign Performance Check768769```770Step 1: List active campaigns771 -> meta_ads_campaigns_list {account_id, status_filter: "ACTIVE"}772773Step 2: Get performance report774 -> meta_ads_insights_report {account_id, period: "last_7d", level: "campaign"}775776Step 3: Analyze performance trends777 -> meta_ads_analysis_performance {account_id}778779Step 4: Break down by demographics780 -> meta_ads_insights_breakdown {account_id, campaign_id, breakdown: "age,gender"}781782Step 5: Check placement performance783 -> meta_ads_analysis_placements {account_id}784```785786### 2. Full Campaign Setup787788```789Step 1: Create campaign (CONFIRM WITH USER)790 -> meta_ads_campaigns_create {account_id, name, objective, daily_budget}791792Step 2: Create ad set with targeting (CONFIRM WITH USER)793 -> meta_ads_ad_sets_create {account_id, campaign_id, name, daily_budget, targeting}794795Step 3: Upload image and create creative796 -> meta_ads_creatives_upload_image {account_id, image_url}797 -> meta_ads_creatives_create {account_id, name, image_hash, link_url, page_id}798799Step 4: Create ad linking to creative (CONFIRM WITH USER)800 -> meta_ads_ads_create {account_id, ad_set_id, name, creative_id}801```802803### 3. Audience & Lookalike Setup804805```806Step 1: List existing audiences807 -> meta_ads_audiences_list {account_id}808809Step 2: Create a website visitor audience (CONFIRM WITH USER)810 -> meta_ads_audiences_create {account_id, name, subtype: "WEBSITE", retention_days, pixel_id}811812Step 3: Create a lookalike based on it (CONFIRM WITH USER)813 -> meta_ads_audiences_create_lookalike {account_id, source_audience_id, country: "JP"}814```815816### 4. A/B Testing with Split Tests817818```819Step 1: Create a split test (CONFIRM WITH USER)820 -> meta_ads_split_tests_create {account_id, name, cells, objectives, start_time, end_time}821822Step 2: Monitor results823 -> meta_ads_split_tests_get {account_id, study_id}824825Step 3: End the test when ready (CONFIRM WITH USER)826 -> meta_ads_split_tests_end {account_id, study_id}827```828829### 5. Product Catalog & DPA830831```832Step 1: Create a catalog (CONFIRM WITH USER)833 -> meta_ads_catalogs_create {account_id, business_id, name}834835Step 2: Add products or create a feed836 -> meta_ads_products_add {account_id, catalog_id, retailer_id, name, ...}837 -> meta_ads_feeds_create {account_id, catalog_id, name, feed_url}838839Step 3: Create a dynamic creative (multi-asset optimization) (CONFIRM WITH USER)840 -> meta_ads_creatives_create_dynamic {account_id, name, page_id, image_hashes, bodies, titles, link_url}841```842843### 6. Lead Generation (Instant Form, end-to-end)844845```846Step 1: Create the Instant Form (CONFIRM WITH USER)847 -> meta_ads_lead_forms_create {account_id, page_id, name, questions, privacy_policy_url, follow_up_action_url}848 Returns: { id: "<form_id>", ... }849850Step 2: Create a Lead Ad creative attached to the form851 -> meta_ads_creatives_create_lead {852 account_id, name, page_id, form_id: "<form_id>",853 link_url: "<https-domain-verified-url>",854 image_hash (or image_url), message, headline,855 call_to_action: "SIGN_UP" # default; APPLY_NOW / LEARN_MORE / etc. also valid856 }857 Returns: { id: "<creative_id>", ... }858859Step 3: Set up the campaign + ad set860 -> meta_ads_campaigns_create {account_id, name, objective: "OUTCOME_LEADS"}861 -> meta_ads_ad_sets_create {862 account_id, campaign_id, name, daily_budget,863 optimization_goal: "LEAD_GENERATION",864 targeting: { ... }865 }866867Step 4: Attach the creative to a new ad868 -> meta_ads_ads_create {account_id, ad_set_id, name, creative_id: "<creative_id>"}869870Step 5: Download leads as they come in (poll)871 -> meta_ads_leads_get {account_id, form_id}872 Or by ad: meta_ads_leads_get_by_ad {account_id, ad_id}873```874875The legacy `LEAD_GENERATION` campaign objective is still accepted by876the API but `OUTCOME_LEADS` is the current (ODAX) canonical name.877878Pre-requisites the API will enforce (catch them before campaign879launch, not after):880- the Page that owns the form must have its lead-form Terms of881 Service accepted (or the form must be created with882 `leadgen_tos_accepted=true`);883- the Page must be linked to a CRM destination or have lead access884 configured, otherwise the lead data sits unread in Meta's UI.885886### 7. Pause / Enable Entities887888```889Pause a campaign:890 -> meta_ads_campaigns_pause {account_id, campaign_id}891892Re-enable it:893 -> meta_ads_campaigns_enable {account_id, campaign_id}894895Same pattern for ad_sets.pause/enable and ads.pause/enable.896```897898### 8. Conversions API (Server-Side Tracking)899900```901Step 1: List pixels and check events902 -> meta_ads_pixels_list {account_id}903 -> meta_ads_pixels_events {account_id, pixel_id}904905Step 2: Send a purchase event (CONFIRM WITH USER)906 -> meta_ads_conversions_send_purchase {account_id, pixel_id, event_time, user_data, currency, value}907```908909## Important Notes910911- **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.912- **account_id format**: Use the `act_` form (a bare numeric id is prefixed), e.g. `"act_123456789"`.913- **Status values**: Meta uses `ACTIVE` / `PAUSED` (not `ENABLED`).914- **Creative-first model**: In Meta Ads, you create a creative object first, then reference its `creative_id` when creating an ad.915- **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`.916- **Conversions API**: Server-side events require hashed `user_data` (email, phone). The SDK handles hashing automatically.