| get_ad_accountsA | Get ad accounts accessible by a user.
amount_spent and balance are returned in currency units (e.g. USD dollars),
not cents.
Args:
access_token: Meta API access token (optional - will use cached token if not provided)
user_id: Meta user ID or "me" for the current user
limit: Maximum number of accounts to return per page (default: 100)
fetch_all: Whether to follow pagination cursors to fetch all accounts (default: True)
|
| get_account_infoA | Get detailed information about a specific ad account.
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
access_token: Meta API access token (optional - will use cached token if not provided)
|
| get_campaignsA | Get campaigns for a Meta Ads account with optional filtering.
Note: By default, the Meta API returns a subset of available fields.
Other fields like 'effective_status', 'spend_cap', 'budget_remaining',
'promoted_object', 'source_campaign_id', etc., might be available but
require specifying them in the API call (currently not exposed by this
tool's parameters).
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
access_token: Meta API access token (optional - will use cached token if not provided)
limit: Maximum number of campaigns to return per page (default: 10)
status_filter: Filter by effective status (e.g., 'ACTIVE', 'PAUSED', 'ARCHIVED').
Maps to the 'effective_status' API parameter, which expects an array
(this function handles the required JSON formatting). Leave empty for all statuses.
objective_filter: Filter by campaign objective(s). Can be a single objective string or a list of objectives.
Valid objectives: 'OUTCOME_AWARENESS', 'OUTCOME_TRAFFIC', 'OUTCOME_ENGAGEMENT',
'OUTCOME_LEADS', 'OUTCOME_SALES', 'OUTCOME_APP_PROMOTION'.
Examples: 'OUTCOME_LEADS' or ['OUTCOME_LEADS', 'OUTCOME_SALES'].
Leave empty for all objectives.
after: Pagination cursor to get the next set of results
fetch_all: Whether to follow pagination cursors to fetch all campaigns (default: False)
|
| get_campaign_detailsA | Get detailed information about a specific campaign.
Note: This function requests a specific set of fields ('id,name,objective,status,...').
The Meta API offers many other fields for campaigns (e.g., 'effective_status', 'source_campaign_id', etc.)
that could be added to the 'fields' parameter in the code if needed.
Args:
campaign_id: Meta Ads campaign ID
access_token: Meta API access token (optional - will use cached token if not provided)
|
| create_campaignA | Create a new campaign in a Meta Ads account.
Note: Campaigns do not support start_time for scheduling — set start_time on the ad set instead.
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
name: Campaign name
objective: Campaign objective (ODAX, outcome-based). Must be one of:
OUTCOME_AWARENESS, OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT,
OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_APP_PROMOTION.
Note: Legacy objectives like BRAND_AWARENESS, LINK_CLICKS,
CONVERSIONS, APP_INSTALLS, etc. are not valid for new
campaigns and will cause a 400 error. Use the outcome-based
values above (e.g., BRAND_AWARENESS → OUTCOME_AWARENESS).
access_token: Meta API access token (optional - will use cached token if not provided)
status: Initial campaign status (default: PAUSED)
special_ad_categories: List of special ad categories if applicable
daily_budget: Daily budget in account currency (in cents) as a string (only used if use_adset_level_budgets=False)
lifetime_budget: Lifetime budget in account currency (in cents) as a string (only used if use_adset_level_budgets=False)
buying_type: Buying type (e.g., 'AUCTION')
bid_strategy: Bid strategy (default: LOWEST_COST_WITHOUT_CAP). Must be one of: 'LOWEST_COST_WITHOUT_CAP', 'LOWEST_COST_WITH_BID_CAP', 'COST_CAP', 'LOWEST_COST_WITH_MIN_ROAS'. WARNING: If you use LOWEST_COST_WITH_BID_CAP or COST_CAP, all child ad sets will require bid_amount to be set.
bid_cap: Bid cap in account currency (in cents) as a string
spend_cap: Spending limit for the campaign in account currency (in cents) as a string
campaign_budget_optimization: Whether to enable campaign budget optimization (only used if use_adset_level_budgets=False)
ab_test_control_setups: Settings for A/B testing (e.g., [{"name":"Creative A", "ad_format":"SINGLE_IMAGE"}])
use_adset_level_budgets: If True, budgets will be set at the ad set level instead of campaign level (default: False)
|
| update_campaignA | Update an existing campaign in a Meta Ads account.
Note: Campaigns do not support start_time for scheduling — set start_time on the ad set instead.
Args:
campaign_id: Meta Ads campaign ID
access_token: Meta API access token (optional - will use cached token if not provided)
name: New campaign name
status: New campaign status (e.g., 'ACTIVE', 'PAUSED')
special_ad_categories: List of special ad categories if applicable
daily_budget: New daily budget in account currency (in cents) as a string.
Set to empty string "" to remove the daily budget.
lifetime_budget: New lifetime budget in account currency (in cents) as a string.
Set to empty string "" to remove the lifetime budget.
bid_strategy: New bid strategy
bid_cap: New bid cap in account currency (in cents) as a string
spend_cap: New spending limit for the campaign in account currency (in cents) as a string
campaign_budget_optimization: Enable/disable campaign budget optimization
objective: New campaign objective (Note: May not always be updatable)
use_adset_level_budgets: If True, removes campaign-level budgets to switch to ad set level budgets
|
| get_adsetsA | Get ad sets for a Meta Ads account with optional filtering by campaign.
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
access_token: Meta API access token (optional - will use cached token if not provided)
limit: Maximum number of ad sets to return per page (default: 10)
campaign_id: Optional campaign ID to filter by
fetch_all: Whether to follow pagination cursors to fetch all ad sets (default: False)
|
| get_adset_detailsA | Get detailed information about a specific ad set.
Args:
adset_id: Meta Ads ad set ID
access_token: Meta API access token (optional - will use cached token if not provided)
Example:
To call this function through MCP, pass the adset_id as the first argument:
{
"args": "YOUR_ADSET_ID"
}
|
| create_adsetA | Create a new ad set in a Meta Ads account.
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
campaign_id: Meta Ads campaign ID this ad set belongs to
name: Ad set name
optimization_goal: Conversion optimization goal. Valid values depend on the campaign objective and destination_type.
OUTCOME_ENGAGEMENT + destination_type=WEBSITE: OFFSITE_CONVERSIONS, LANDING_PAGE_VIEWS, LINK_CLICKS, IMPRESSIONS, REACH.
OUTCOME_ENGAGEMENT + On Post: POST_ENGAGEMENT, IMPRESSIONS, REACH.
OUTCOME_ENGAGEMENT + On Video: THRUPLAY, TWO_SECOND_CONTINUOUS_VIDEO_VIEWS.
OUTCOME_ENGAGEMENT + On Event: EVENT_RESPONSES, IMPRESSIONS, POST_ENGAGEMENT, REACH.
OUTCOME_ENGAGEMENT + On Page: PAGE_LIKES.
OUTCOME_ENGAGEMENT + Messaging (MESSENGER/WHATSAPP/INSTAGRAM_DIRECT): CONVERSATIONS, LINK_CLICKS.
OUTCOME_TRAFFIC + WEBSITE: LANDING_PAGE_VIEWS, LINK_CLICKS, IMPRESSIONS, REACH.
OUTCOME_AWARENESS: REACH, IMPRESSIONS, AD_RECALL_LIFT, THRUPLAY.
OUTCOME_LEADS: LEAD_GENERATION, QUALITY_LEAD (forms), QUALITY_CALL (calls), OFFSITE_CONVERSIONS, LINK_CLICKS (website).
OUTCOME_SALES: OFFSITE_CONVERSIONS, VALUE, CONVERSATIONS, LINK_CLICKS, IMPRESSIONS, REACH.
OUTCOME_APP_PROMOTION: APP_INSTALLS, APP_INSTALLS_AND_OFFSITE_CONVERSIONS, VALUE.
billing_event: How you're charged (e.g., 'IMPRESSIONS', 'LINK_CLICKS')
status: Initial ad set status (default: PAUSED)
daily_budget: Daily budget in account currency (in cents) as a string
lifetime_budget: Lifetime budget in account currency (in cents) as a string
targeting: Targeting specs (age, location, interests, etc).
targeting_automation.advantage_audience defaults to 0 if not set (Meta API v24+ requirement).
Set to 1 to enable Advantage+ Audience (requires age_max>=65). Use search_interests for interest IDs.
bid_amount: Bid amount in account currency (in cents).
REQUIRED for: LOWEST_COST_WITH_BID_CAP, COST_CAP, TARGET_COST.
NOT USED by: LOWEST_COST_WITH_MIN_ROAS (uses bid_constraints instead).
May also be required if the parent campaign's bid strategy requires it.
bid_strategy: Bid strategy. Valid values:
- 'LOWEST_COST_WITHOUT_CAP' (recommended) - no bid_amount required
- 'LOWEST_COST_WITH_BID_CAP' - REQUIRES bid_amount
- 'COST_CAP' - REQUIRES bid_amount
- 'LOWEST_COST_WITH_MIN_ROAS' - REQUIRES bid_constraints with roas_average_floor,
and optimization_goal='VALUE'. Does NOT use bid_amount.
Note: 'LOWEST_COST' is NOT valid - use 'LOWEST_COST_WITHOUT_CAP'.
Campaign-level bid strategy may constrain ad set choices.
bid_constraints: Bid constraints dict. Required for LOWEST_COST_WITH_MIN_ROAS.
Use {"roas_average_floor": <value>} where value = target ROAS * 10000.
Example: 2.0x ROAS -> {"roas_average_floor": 20000}
start_time: Start time in ISO 8601 format (e.g., '2023-12-01T12:00:00-0800').
To schedule future delivery: set start_time to a future date and status=ACTIVE.
Meta will show effective_status as SCHEDULED and automatically begin delivery at start_time.
NOTE: Only ad set start_time controls delivery scheduling. Campaigns do not support start_time.
end_time: End time in ISO 8601 format. Required when lifetime_budget is specified.
dsa_beneficiary: DSA beneficiary for European compliance (person/org that benefits from ads).
Required for EU-targeted ad sets along with dsa_payor.
dsa_payor: DSA payor for European compliance (person/org paying for the ads).
Required for EU-targeted ad sets along with dsa_beneficiary.
promoted_object: App config for APP_INSTALLS. Required: application_id, object_store_url.
destination_type: Where users go after click. Common values: 'WEBSITE', 'WHATSAPP', 'MESSENGER',
'INSTAGRAM_DIRECT', 'ON_AD', 'APP', 'FACEBOOK', 'SHOP_AUTOMATIC'.
Also supports multi-channel combos like 'MESSAGING_MESSENGER_WHATSAPP'.
is_dynamic_creative: Enable Dynamic Creative for this ad set.
frequency_control_specs: Frequency cap specs. MUST be set at creation time — Meta makes this field
immutable after the ad set is created (error 1815198).
Only works with OUTCOME_AWARENESS campaigns + optimization_goal REACH or THRUPLAY.
Example: [{"event": "IMPRESSIONS", "interval_days": 7, "max_frequency": 1}]
multi_advertiser_ads: Set to 0 to opt out of Multi-Advertiser Ads, 1 to opt in.
This is a TOP-LEVEL ad set parameter — do NOT put it inside the targeting object.
regional_regulated_categories: List of regional regulated categories for the ad set.
Required for ads targeting regulated regions (Taiwan, Australia, etc.).
Valid values: TAIWAN_FINSERV, TAIWAN_UNIVERSAL, AUSTRALIA_FINSERV,
INDIA_FINSERV, SINGAPORE_UNIVERSAL, THAILAND_UNIVERSAL.
Example: ["TAIWAN_UNIVERSAL"] or ["TAIWAN_FINSERV", "TAIWAN_UNIVERSAL"]
regional_regulation_identities: Dict of verified identity IDs for regional transparency compliance.
Required when regional_regulated_categories is set.
The identity IDs come from completing advertiser verification in Meta Business Settings.
Keys depend on the categories declared:
- TAIWAN_UNIVERSAL: taiwan_universal_beneficiary, taiwan_universal_payer
- TAIWAN_FINSERV: taiwan_finserv_beneficiary, taiwan_finserv_payer
- AUSTRALIA_FINSERV: australia_finserv_beneficiary, australia_finserv_payer
- SINGAPORE_UNIVERSAL: singapore_universal_beneficiary, singapore_universal_payer
Example: {"taiwan_universal_beneficiary": "<id>", "taiwan_universal_payer": "<id>"}
attribution_spec: Attribution window specification for the ad set. Controls how conversions are
attributed to ads. Default is 7-day click if not specified.
Example for 1-day click: [{"event_type": "CLICK_THROUGH", "window_days": 1}]
Example for 1-day click + 1-day view: [{"event_type": "CLICK_THROUGH", "window_days": 1}, {"event_type": "VIEW_THROUGH", "window_days": 1}]
Valid event_type values: CLICK_THROUGH, VIEW_THROUGH.
Valid window_days values: 1, 7, 28 (depends on event_type and optimization_goal).
access_token: Meta API access token (optional - will use cached token if not provided)
|
| update_adsetA | Update an ad set with new settings including frequency caps and budgets.
Args:
adset_id: Meta Ads ad set ID
name: New ad set name
frequency_control_specs: Frequency control specs
(e.g. [{"event": "IMPRESSIONS", "interval_days": 7, "max_frequency": 3}])
bid_strategy: Bid strategy. Valid values:
- 'LOWEST_COST_WITHOUT_CAP' (recommended) - no bid_amount required
- 'LOWEST_COST_WITH_BID_CAP' - REQUIRES bid_amount
- 'COST_CAP' - REQUIRES bid_amount
- 'LOWEST_COST_WITH_MIN_ROAS' - REQUIRES bid_constraints with roas_average_floor
Note: 'LOWEST_COST' is NOT valid - use 'LOWEST_COST_WITHOUT_CAP'.
bid_amount: Bid amount in cents. Required for LOWEST_COST_WITH_BID_CAP, COST_CAP, TARGET_COST.
NOT USED by LOWEST_COST_WITH_MIN_ROAS (uses bid_constraints instead).
bid_constraints: Bid constraints dict. Required for LOWEST_COST_WITH_MIN_ROAS.
Use {"roas_average_floor": <value>} where value = target ROAS * 10000.
Example: 2.0x ROAS -> {"roas_average_floor": 20000}
status: Update ad set status (ACTIVE, PAUSED, etc.)
targeting: Complete targeting specifications (replaces existing targeting)
optimization_goal: Conversion optimization goal (e.g., 'LINK_CLICKS', 'CONVERSIONS', 'VALUE')
daily_budget: Daily budget in account currency (in cents)
lifetime_budget: Lifetime budget in account currency (in cents)
is_dynamic_creative: Enable/disable Dynamic Creative for this ad set.
WARNING: This field is immutable after ad set creation. Meta's API will
return success but silently ignore the change. To change this, create a new ad set.
start_time: Start time in ISO 8601 format (e.g., '2023-12-01T12:00:00-0800').
Use with status=ACTIVE to schedule the ad set for future delivery (effective_status will be SCHEDULED until start_time).
end_time: End time in ISO 8601 format. Required when lifetime_budget is specified.
dsa_beneficiary: DSA beneficiary for European compliance (person/org that benefits from ads).
Required for EU-targeted ad sets along with dsa_payor.
dsa_payor: DSA payor for European compliance (person/org paying for the ads).
Required for EU-targeted ad sets along with dsa_beneficiary.
multi_advertiser_ads: Set to 0 to opt out of Multi-Advertiser Ads, 1 to opt in.
This is a TOP-LEVEL ad set parameter — do NOT put it inside the targeting object.
regional_regulated_categories: List of regional regulated categories for the ad set.
Required for ads targeting regulated regions (Taiwan, Australia, etc.).
Valid values: TAIWAN_FINSERV, TAIWAN_UNIVERSAL, AUSTRALIA_FINSERV,
INDIA_FINSERV, SINGAPORE_UNIVERSAL, THAILAND_UNIVERSAL.
Set to null/empty to remove existing categories.
regional_regulation_identities: Dict of verified identity IDs for regional transparency compliance.
Required when regional_regulated_categories is set.
Set individual keys to null to remove them.
attribution_spec: Attribution window specification for the ad set.
WARNING: Meta no longer supports updating attribution_spec after ad set creation
(error 1504040). To change attribution windows, create a new ad set instead.
This parameter is kept for compatibility but will be rejected by Meta's API.
Valid event_type values: CLICK_THROUGH, VIEW_THROUGH.
Valid window_days values: 1, 7, 28 (depends on event_type and optimization_goal).
access_token: Meta API access token (optional - will use cached token if not provided)
|
| get_adsA | Get ads for a Meta Ads account with optional filtering.
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
access_token: Meta API access token (optional - will use cached token if not provided)
limit: Maximum number of ads to return per page (default: 10)
campaign_id: Optional campaign ID to filter by
adset_id: Optional ad set ID to filter by
after: Pagination cursor to get the next set of results
fetch_all: Whether to follow pagination cursors to fetch all ads (default: False)
|
| get_ad_detailsA | Get detailed information about a specific ad.
Args:
ad_id: Meta Ads ad ID
access_token: Meta API access token (optional - will use cached token if not provided)
|
| get_creative_detailsA | Get detailed information about a specific ad creative by its ID. Args:
creative_id: Meta Ads creative ID (required)
access_token: Meta API access token (optional)
|
| create_adA | Create a new ad with an existing creative.
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
name: Ad name
adset_id: Ad set ID where this ad will be placed
creative_id: ID of an existing creative to use
status: Initial ad status (default: PAUSED)
bid_amount: Optional bid amount in account currency (in cents)
tracking_specs: Optional tracking specifications (e.g., for pixel events).
Example: [{"action.type":"offsite_conversion","fb_pixel":["YOUR_PIXEL_ID"]}]
access_token: Meta API access token (optional - will use cached token if not provided)
Note:
Dynamic Creative creatives require the parent ad set to have `is_dynamic_creative=true`.
Otherwise, ad creation will fail with error_subcode 1885998.
|
| get_ad_creativesA | Get creative details for a specific ad. Requires an ad_id (not account_id). Use get_ads first to find ad IDs.
Args:
ad_id: Meta Ads ad ID (required)
access_token: Meta API access token (optional - will use cached token if not provided)
|
| get_ad_imageA | Get, download, and visualize a Meta ad image in one step. Useful to see the image in the LLM.
Args:
ad_id: Meta Ads ad ID
access_token: Meta API access token (optional - will use cached token if not provided)
Returns:
The ad image ready for direct visual analysis
|
| get_ad_videoA | Get video details and source URL for a Meta ad video creative. Returns the video source URL
(direct download link), thumbnail URL, and metadata (title, description, duration).
Provide either ad_id (to auto-extract the video from the ad creative) or video_id directly.
Providing account_id is strongly recommended — it enables the advideos edge which works
with Business Manager tokens (avoids error 100/33 and error #10 on account-uploaded videos).
Args:
ad_id: Meta Ads ad ID (will extract video_id from the ad creative)
video_id: Meta video ID (use this if you already have it from get_ad_creatives)
account_id: Ad account ID (e.g. "act_123" or "123"). Enables advideos edge lookup.
access_token: Meta API access token (optional - will use cached token if not provided)
|
| update_adA | Update an ad with new settings.
Args:
ad_id: Meta Ads ad ID
name: New ad name
status: Update ad status (ACTIVE, PAUSED, etc.)
bid_amount: Bid amount in account currency (in cents for USD)
tracking_specs: Optional tracking specifications (e.g., for pixel events).
creative_id: ID of the creative to associate with this ad (changes the ad's image/content)
access_token: Meta API access token (optional - will use cached token if not provided)
|
| upload_ad_imageA | Upload an image to use in Meta Ads creatives.
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
access_token: Meta API access token (optional - will use cached token if not provided)
file: Data URL or raw base64 string of the image (e.g., "data:image/png;base64,iVBORw0KG...")
image_url: Direct URL to an image to fetch and upload
name: Optional name for the image (default: filename)
Returns:
JSON response with image details including hash for creative creation
|
| compute_image_cropsA | Compute image_crops coordinates for a source image of the given dimensions.
Returns the image_crops dict ready to pass directly to create_ad_creative
or bulk_create_ad_creatives. For each crop key the result is the largest
centered region that fits within the source image while matching the key's
aspect ratio — equivalent to "Original" crop (no content is cut off beyond
what the ratio requires).
Args:
image_width: Width of the source image in pixels (e.g. 1080).
image_height: Height of the source image in pixels (e.g. 1080).
crop_keys: Optional list of specific crop keys to compute. Defaults to
all 6 keys accepted by Meta's API:
"100x100" — 1:1 square (Feed, Marketplace, Search)
"100x72" — ~1.39:1 horizontal (Marketplace, some placements)
"400x500" — 4:5 portrait (Feed on mobile, Stories fallback)
"400x150" — ~2.67:1 wide banner (Audience Network)
"600x360" — ~1.67:1 horizontal (Right column, some placements)
"90x160" — 9:16 tall portrait (Stories)
Returns:
JSON with the image_crops dict (ready for copy-paste into create_ad_creative),
plus validation notes for any invalid keys requested.
|
| create_ad_creativeA | Create a new ad creative using an uploaded image hash or video ID.
Supports four creative modes:
- **Simple image/video**: Single image_hash or video_id with object_story_spec
- **Multi-variant copy**: Use plural text params (messages[], headlines[], descriptions[]) to test
multiple text variants with a single image/video. No optimization_type or is_dynamic_creative needed.
- **Dynamic Creative**: Multiple variants with dynamic_creative_spec (requires is_dynamic_creative on ad set)
- **FLEX/DOF (Advantage+)**: Set optimization_type="DEGREES_OF_FREEDOM" for Meta to auto-optimize
across all asset combinations without requiring is_dynamic_creative on the ad set
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
image_hash: Hash of a single uploaded image (cannot be used with image_hashes or video_id)
access_token: Meta API access token (optional - will use cached token if not provided)
name: Creative name
page_id: Facebook Page ID (string or int; coerced to string)
link_url: Destination URL for the ad (required unless using lead_gen_form_id)
message: Single ad copy/text (cannot be used with messages)
messages: List of primary text variants for multi-variant copy testing (cannot be used with message)
headline: Single headline for simple ads (cannot be used with headlines)
headlines: List of headline variants for multi-variant copy testing (cannot be used with headline)
description: Single description for simple ads (cannot be used with descriptions)
descriptions: List of description variants for multi-variant copy testing (cannot be used with description)
image_hashes: List of image hashes for FLEX creatives (up to 10, cannot be used with image_hash or video_id)
video_id: Meta video ID for video creatives (cannot be used with image_hash or image_hashes).
Upload a video first via the Meta API, then use the returned video ID here.
thumbnail_url: Thumbnail image URL for video creatives. Recommended when using video_id.
Meta will auto-generate a thumbnail if not provided.
optimization_type: Optional. Set to "DEGREES_OF_FREEDOM" for FLEX (Advantage+) creatives that
allow Meta to auto-optimize across all asset combinations. Not required for
text-only multi-variant creatives (messages[], headlines[], descriptions[]
work without it). When using DEGREES_OF_FREEDOM, at least one asset field
(image_hashes, messages, headlines, or descriptions) must contain more than
one variant.
NOTE: If asset_customization_rules is also provided, optimization_type
is automatically removed because Meta ignores placement rules for DOF
creatives. The creative will use regular dynamic creative mode instead.
dynamic_creative_spec: Dynamic creative optimization settings
call_to_action_type: Call to action button type (e.g., 'LEARN_MORE', 'SIGN_UP', 'SHOP_NOW',
'CALL_NOW'). When using CALL_NOW, also provide phone_number.
lead_gen_form_id: Lead generation form ID for lead generation campaigns. Required when using
lead generation CTAs like 'SIGN_UP', 'GET_OFFER', 'SUBSCRIBE', etc.
instagram_actor_id: Instagram account ID for Instagram placements (must be a string
to avoid JavaScript integer precision loss for IDs exceeding
Number.MAX_SAFE_INTEGER). Sent as instagram_user_id inside
object_story_spec (Meta deprecated instagram_actor_id in Jan 2026).
ad_formats: List of ad format strings for asset_feed_spec (e.g., ["AUTOMATIC_FORMAT"] for
Flexible ads, ["SINGLE_IMAGE"] for single image, ["SINGLE_VIDEO"] for video).
When optimization_type is "DEGREES_OF_FREEDOM" with image_hashes, defaults to
["AUTOMATIC_FORMAT"] (Flexible format). For video creatives, defaults to
["SINGLE_VIDEO"]. Otherwise defaults to ["SINGLE_IMAGE"].
asset_customization_rules: List of placement-specific asset overrides for asset_feed_spec.
phone_number: Phone number for CALL_NOW call-to-action ads (click-to-call).
Required when call_to_action_type is CALL_NOW. Use E.164 format
(e.g., "+18005551234"). The number is passed to Meta in
call_to_action.value.phone_number. Common use case: geo-routed
call ads with different phone numbers per ad set.
creative_features_spec: Advantage+ Creative feature opt-ins/opt-outs. Controls individual
creative enhancements like image_touchups, text_optimizations, inline_comment,
add_text_overlay, music, 3d_animation, etc. Each feature is a dict with
"enroll_status" set to "OPT_IN" or "OPT_OUT".
Example: {"image_touchups": {"enroll_status": "OPT_IN"},
"inline_comment": {"enroll_status": "OPT_IN"}}
Sent to Meta as degrees_of_freedom_spec.creative_features_spec.
url_tags: URL tracking parameters appended to the destination URL (e.g.,
"utm_source=facebook&utm_medium=cpc&utm_campaign=spring_sale").
Sets the url_tags field on the creative.
caption: Display URL shown in the ad (e.g., "example.com/shoes"). Sets the
caption field in link_data. If not provided, Meta auto-generates it
from the destination URL. Only applies to image (link_data) creatives.
image_crops: Crop coordinates for different aspect ratios. Applied in link_data for
image creatives.
Use the compute_image_crops tool first to get the correct coordinates
for your specific image dimensions — it computes centered crop boxes
for any source size automatically.
Valid crop keys (only these 6 are accepted by Meta's API):
"100x100" — 1:1 square (Feed, Marketplace, Search)
"100x72" — ~1.39:1 horizontal (Marketplace, some placements)
"400x500" — 4:5 portrait (Feed on mobile, Stories fallback)
"400x150" — ~2.67:1 wide banner (Audience Network)
"600x360" — ~1.67:1 horizontal (Right column, some placements)
"90x160" — 9:16 tall portrait (Stories)
Format: {"100x100": [[x1,y1],[x2,y2]], "400x500": [[x1,y1],[x2,y2]]}
Coordinates are pixel-based (top-left and bottom-right corners).
The bounding box aspect ratio must match the key ratio as closely as possible.
Image origin (0,0) is the upper-left corner.
Omit to let Meta auto-crop (default for horizontal is 1.91:1 recommended).
asset_customization_rules: Lets you assign different images or videos to specific placement groups
(e.g., feed vs. stories). Only valid with image_hashes or plural asset params.
Each rule uses a user-friendly format that is automatically translated to
Meta's API format (adlabels + customization_spec positions):
- placement_groups: list of placement group names
Valid values: FEED, STORY, MESSENGER, INSTREAM_VIDEO, SEARCH, SHOP,
AUDIENCE_NETWORK
- customization_spec: dict specifying the asset to use for those placements
Supported keys: image_hashes (list), video_ids (list),
bodies, titles, descriptions (text overrides)
All image hashes referenced in rules must also be in image_hashes.
Example (feed gets one image, stories gets another):
[
{"placement_groups": ["FEED"],
"customization_spec": {"image_hashes": ["<feed_hash>"]}},
{"placement_groups": ["STORY"],
"customization_spec": {"image_hashes": ["<story_hash>"]}}
]
Returns:
JSON response with created creative details
|
| update_ad_creativeA | Update an existing ad creative's name or optimization settings.
IMPORTANT — Meta API limitation: The Meta API does NOT allow updating content
fields (message, headline, description, CTA, image, video, URL) on existing
creatives. Only the creative `name` and optimization settings (asset_feed_spec)
can be changed. To change ad content, create a new creative with the desired
content and update the ad to reference the new creative via `update_ad`.
Args:
creative_id: Meta Ads creative ID to update
access_token: Meta API access token (optional - will use cached token if not provided)
name: New creative name (this is the most reliable update)
message: New ad copy/text — NOTE: Meta API may reject this on existing creatives
messages: List of primary text variants — NOTE: Meta API may reject this on existing creatives
headline: Single headline — NOTE: Meta API may reject this on existing creatives
headlines: New list of headlines — NOTE: Meta API may reject this on existing creatives
description: Single description — NOTE: Meta API may reject this on existing creatives
descriptions: New list of descriptions — NOTE: Meta API may reject this on existing creatives
optimization_type: Set to "DEGREES_OF_FREEDOM" for FLEX (Advantage+) creatives
dynamic_creative_spec: New dynamic creative optimization settings
call_to_action_type: New call to action button type — NOTE: Meta API may reject this on existing creatives
lead_gen_form_id: Lead generation form ID for lead generation campaigns
ad_formats: List of ad format strings for asset_feed_spec (e.g., ["AUTOMATIC_FORMAT"] for
Flexible ads, ["SINGLE_IMAGE"] for single image)
creative_features_spec: Dict of Advantage+ Creative feature opt-ins/opt-outs.
Each key is a feature name, value is {"enroll_status": "OPT_IN"|"OPT_OUT"}.
Sent as a top-level field (not inside degrees_of_freedom_spec).
Returns:
JSON response with updated creative details
|
| search_pages_by_nameA | Search for pages by name within an account.
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
access_token: Meta API access token (optional - will use cached token if not provided)
search_term: Search term to find pages by name (optional - returns all pages if not provided)
Returns:
JSON response with matching pages
|
| get_account_pagesA | Get pages associated with a Meta Ads account.
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
access_token: Meta API access token (optional - will use cached token if not provided)
Returns:
JSON response with pages associated with the account
|
| get_insightsA | Get performance insights for a campaign, ad set, ad or account.
Args:
object_id: ID of the campaign, ad set, ad or account. You can also use the alias parameters below.
account_id: Alias for object_id when querying account-level insights
campaign_id: Alias for object_id when querying campaign-level insights
adset_id: Alias for object_id when querying ad-set-level insights
ad_id: Alias for object_id when querying ad-level insights
access_token: Meta API access token (optional - will use cached token if not provided)
time_range: Either a preset time range string or a dictionary with "since" and "until" dates in YYYY-MM-DD format
Preset options: today, yesterday, this_month, last_month, this_quarter, maximum, data_maximum,
last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun,
last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year
Dictionary example: {"since":"2023-01-01","until":"2023-01-31"}
breakdown: Optional breakdown dimension. Valid values include:
Demographic: age, gender, country, region, dma
Platform/Device: device_platform, platform_position, publisher_platform, impression_device
Creative Assets: ad_format_asset, body_asset, call_to_action_asset, description_asset,
image_asset, link_url_asset, title_asset, video_asset, media_asset_url,
media_creator, media_destination_url, media_format, media_origin_url,
media_text_content, media_type, creative_relaxation_asset_type,
flexible_format_asset_type, gen_ai_asset_type
Campaign/Ad Attributes: breakdown_ad_objective, breakdown_reporting_ad_id, app_id, product_id
Conversion Tracking: coarse_conversion_value, conversion_destination, standard_event_content_type,
signal_source_bucket, is_conversion_id_modeled, fidelity_type, redownload
Time-based: hourly_stats_aggregated_by_advertiser_time_zone,
hourly_stats_aggregated_by_audience_time_zone, frequency_value
Extensions/Landing: ad_extension_domain, ad_extension_url, landing_destination,
mdsa_landing_destination
Attribution: sot_attribution_model_type, sot_attribution_window, sot_channel,
sot_event_type, sot_source
Mobile/SKAN: skan_campaign_id, skan_conversion_id, skan_version, postback_sequence_index
CRM/Business: crm_advertiser_l12_territory_ids, crm_advertiser_subvertical_id,
crm_advertiser_vertical_id, crm_ult_advertiser_id, user_persona_id, user_persona_name
Advanced: hsid, is_auto_advance, is_rendered_as_delayed_skip_ad, mmm, place_page_id,
marketing_messages_btn_name, impression_view_time_advertiser_hour_v2, comscore_market,
comscore_market_code
level: Level of aggregation (ad, adset, campaign, account)
limit: Maximum number of results to return per page (default: 25, Meta API allows much higher values)
after: Pagination cursor to get the next set of results. Use the 'after' cursor from previous response's paging.next field.
action_attribution_windows: Optional list of attribution windows (e.g., ["1d_click", "7d_click", "1d_view"]).
When specified, actions include additional fields for each window. The 'value' field always shows 7d_click.
compact: When True, strips redundant action-type duplicates from the response
(omni_*, onsite_web_*, offsite_conversion.fb_pixel_*, etc.) to reduce
payload size by ~60%. The canonical action types (purchase, add_to_cart,
view_content, etc.) are always preserved. Default: False.
Note on response size: This tool always returns a fixed set of fields (impressions, clicks,
spend, cpc, cpm, ctr, reach, actions, action_values, etc.) and cannot filter to a subset.
For large result sets (50+ rows), the actions/action_values arrays can make responses very
large (1–2MB+). If you only need specific metrics like spend or impressions, consider using
bulk_get_insights with compact=true and the fields parameter:
bulk_get_insights(level="ad", account_ids=[...], compact=true, fields=["spend", "impressions"])
bulk_get_insights supports level="ad", "adset", "campaign", and "account".
|
| get_login_linkA | Get a clickable login link for Meta Ads authentication.
NOTE: This method should only be used if you're using your own Facebook app.
If using Pipeboard authentication (recommended), set the PIPEBOARD_API_TOKEN
environment variable instead (token obtainable via https://pipeboard.co).
Args:
access_token: Meta API access token (optional - will use cached token if not provided)
Returns:
A clickable resource link for Meta authentication
|
| search_ads_archiveA | Search the Facebook Ads Library archive.
Args:
search_terms: The search query for ads.
ad_reached_countries: List of country codes (e.g., ["US", "GB"]).
access_token: Meta API access token (optional - will use cached token if not provided).
ad_type: Type of ads to search for (e.g., POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, ALL).
limit: Maximum number of ads to return.
fields: Comma-separated string of fields to retrieve for each ad.
Example Usage via curl equivalent:
curl -G \
-d "search_terms='california'" \
-d "ad_type=POLITICAL_AND_ISSUE_ADS" \
-d "ad_reached_countries=['US']" \
-d "fields=ad_snapshot_url,spend" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/ads_archive"
|
| create_budget_scheduleA | Create a budget schedule for a Meta Ads campaign.
Allows scheduling budget increases based on anticipated high-demand periods.
The times should be provided as Unix timestamps.
Args:
campaign_id: Meta Ads campaign ID.
budget_value: Amount of budget increase. Interpreted based on budget_value_type.
budget_value_type: Type of budget value - "ABSOLUTE" or "MULTIPLIER".
time_start: Unix timestamp for when the high demand period should start.
time_end: Unix timestamp for when the high demand period should end.
access_token: Meta API access token (optional - will use cached token if not provided).
Returns:
A JSON string containing the ID of the created budget schedule or an error message.
|
| search_interestsA | Search for interest targeting options by keyword.
Args:
query: Search term for interests (e.g., "baseball", "cooking", "travel")
access_token: Meta API access token (optional - will use cached token if not provided)
limit: Maximum number of results to return (default: 25)
Returns:
JSON string containing interest data with id, name, audience_size, and path fields
|
| get_interest_suggestionsA | Get interest suggestions based on existing interests.
Args:
interest_list: List of interest names to get suggestions for (e.g., ["Basketball", "Soccer"])
access_token: Meta API access token (optional - will use cached token if not provided)
limit: Maximum number of suggestions to return (default: 25)
Returns:
JSON string containing suggested interests with id, name, audience_size, and description fields
|
| estimate_audience_sizeA | Estimate audience size for targeting specifications using Meta's delivery_estimate API.
This function provides comprehensive audience estimation for complex targeting combinations
including demographics, geography, interests, and behaviors. It also maintains backwards
compatibility for simple interest validation.
Args:
access_token: Meta API access token (optional - will use cached token if not provided)
account_id: Meta Ads account ID (format: act_XXXXXXXXX) - required for comprehensive estimation
targeting: Complete targeting specification including demographics, geography, interests, etc.
Example: {
"age_min": 25,
"age_max": 65,
"geo_locations": {"countries": ["PL"]},
"flexible_spec": [
{"interests": [{"id": "6003371567474"}]},
{"interests": [{"id": "6003462346642"}]}
]
}
optimization_goal: Optimization goal for estimation (default: "REACH").
Options: "REACH", "LINK_CLICKS", "IMPRESSIONS", "CONVERSIONS", etc.
interest_list: [DEPRECATED - for backwards compatibility] List of interest names to validate
interest_fbid_list: [DEPRECATED - for backwards compatibility] List of interest IDs to validate
Returns:
JSON string with audience estimation results including estimated_audience_size,
reach_estimate, and targeting validation
|
| search_behaviorsA | Get all available behavior targeting options.
Args:
access_token: Meta API access token (optional - will use cached token if not provided)
limit: Maximum number of results to return (default: 50)
Returns:
JSON string containing behavior targeting options with id, name, audience_size bounds, path, and description
|
| search_demographicsA | Get demographic targeting options.
Args:
access_token: Meta API access token (optional - will use cached token if not provided)
demographic_class: Type of demographics to retrieve. Options: 'demographics', 'life_events',
'industries', 'income', 'family_statuses', 'user_device', 'user_os' (default: 'demographics')
limit: Maximum number of results to return (default: 50)
Returns:
JSON string containing demographic targeting options with id, name, audience_size bounds, path, and description
|
| search_geo_locationsA | Search for geographic targeting locations.
Args:
query: Search term for locations (e.g., "New York", "California", "Japan")
access_token: Meta API access token (optional - will use cached token if not provided)
location_types: Types of locations to search. Options: ['country', 'region', 'city', 'zip',
'geo_market', 'electoral_district']. If not specified, searches all types.
limit: Maximum number of results to return (default: 25)
Returns:
JSON string containing location data with key, name, type, and geographic hierarchy information
|
| searchA | Search through Meta Ads data and return matching record IDs.
It searches across ad accounts, campaigns, ads, pages, and businesses to find relevant records
based on the provided query.
Args:
query: Search query string to find relevant Meta Ads records
access_token: Meta API access token (optional - will use cached token if not provided)
Returns:
JSON response with list of matching record IDs
Example Usage:
search(query="active campaigns")
search(query="account spending")
search(query="facebook ads performance")
search(query="facebook pages")
search(query="user businesses")
|
| fetchA | Fetch a record previously returned by the 'search' tool in the same session.
IMPORTANT LIMITATIONS:
- This tool ONLY returns records that were cached by a prior 'search' call.
It does NOT make direct API calls to Meta. If the record was not found by
'search' first, this tool will return "Record not found".
- Do NOT use this tool to look up campaigns, adsets, or ads by ID directly.
For direct lookups by ID, use these tools instead:
- get_campaign_details(campaign_id=...) - for campaigns
- get_adset_details(adset_id=...) - for ad sets
- get_ads(account_id=..., campaign_id=...) - for ads
- get_adsets(account_id=..., campaign_id=...) - for ad sets in a campaign
Args:
id: The record ID to fetch (format: "type:id", e.g., "account:act_123456").
Must have been returned by a previous 'search' call.
Returns:
JSON response with record data, or "Record not found" if the record
was not previously cached by 'search'.
|
