Meta Ads MCP Server

Compute image_crops coordinates for a source image. For each requested key, returns the largest centered region that fits the source while matching that key's aspect ratio (equivalent to Meta's "Original" crop — no content cut beyond the ratio).

Valid keys (Meta accepts only these 6): 100x100 — 1:1 square (Feed, Marketplace) 100x72 — ~1.39:1 horizontal (Marketplace) 400x500 — 4:5 portrait (Feed mobile, Stories fallback) 400x150 — ~2.67:1 banner (Audience Network) 600x360 — ~1.67:1 horizontal (Right column) 90x160 — 9:16 portrait (Stories)

Pass the returned image_crops dict to meta_ads_create_ad_creative.

Estimate audience size for a targeting spec using Meta's delivery_estimate / reachestimate endpoints.

Args:

• act_id (string): Ad account ID prefixed with 'act_'.
• targeting (object): Full targeting spec (geo_locations, age_min, age_max, interests, flexible_spec, etc.).
• optimization_goal (string, optional): Default 'REACH'. Other common values: LINK_CLICKS, LANDING_PAGE_VIEWS, OFFSITE_CONVERSIONS, IMPRESSIONS.

Returns: Estimated audience size bounds plus the raw API response.

Fetch the next or previous page of results from a Meta Graph API pagination URL.

Use this tool whenever a Meta Ads tool response contains a paging.next or paging.previous URL. The pagination URL already includes the access token and all necessary parameters.

Args:

• url (string): The complete pagination URL from response.paging.next or response.paging.previous

Returns: The next/previous page of results in the same format as the original response.

Examples:

• Use when: response.paging.next exists after calling meta_ads_get_adaccount_insights
• Use when: response.paging.next exists after calling meta_ads_get_campaigns_by_adaccount
• Use when: "Get all pages of results automatically"

Note: The pagination URL already contains the access token — do NOT add or modify it.

List Facebook Pages reachable from the access token's user. These are the candidate page_id values for create_ad_creative.

Args:

• act_id (string, optional): Reserved for parity with the Python reference; Meta returns pages bound to the user/token, not the ad account, so this is currently unused.

Returns: { data: [{ id, name, username, category, fan_count, link, verification_status, picture }] }

Retrieve the change history (activity log) for a Meta ad account.

Returns key updates to the account and associated ad objects, including status changes, budget updates, targeting changes, and more. By default returns one week of data.

Args:

• act_id (string): Ad account ID prefixed with 'act_', e.g., 'act_1234567890'
• fields (string[]): Fields to retrieve. Available: actor_id, actor_name, application_id, application_name, changed_data, date_time_in_timezone, event_time, event_type, extra_data, object_id, object_name, object_type, translated_event_type
• limit (number): Maximum activities per page
• after / before (string): Pagination cursors
• time_range (object): Custom range {'since':'YYYY-MM-DD','until':'YYYY-MM-DD'}. Overrides since/until
• since (string): Start date in YYYY-MM-DD format (ignored if time_range is set)
• until (string): End date in YYYY-MM-DD format (ignored if time_range is set)

Returns: Object with data (activity array) and paging. Each activity record contains who made the change, what was changed, when, and the specific details.

• actor_name (string): Name of the user who made the change
• object_type (string): Type of object: AD, ADSET, CAMPAIGN, ACCOUNT, IMAGE, REPORT, etc.
• translated_event_type (string): Human-readable description, e.g., 'ad created', 'campaign budget updated'
• event_time (string): Timestamp of the event
• changed_data (string): JSON detailing what changed

Use meta_ads_fetch_pagination_url with paging.next to retrieve additional pages.

Examples:

• Use when: "Show me all changes made to my ad account in the last week"
• Use when: "Who changed the budget on this account in January 2024?"

Retrieve the change history (activity log) for a specific Meta ad set.

Returns updates to the ad set including status changes, budget updates, targeting changes, and more. By default returns one week of data.

Args:

• adset_id (string): Ad set ID, e.g., '23843211234567'
• fields (string[]): Fields to retrieve. Available: actor_id, actor_name, application_id, application_name, changed_data, date_time_in_timezone, event_time, event_type, extra_data, object_id, object_name, object_type, translated_event_type
• limit (number): Maximum activities per page
• after / before (string): Pagination cursors
• time_range (object): Custom range {'since':'YYYY-MM-DD','until':'YYYY-MM-DD'}. Overrides since/until
• since (string): Start date in YYYY-MM-DD format (ignored if time_range is set)
• until (string): End date in YYYY-MM-DD format (ignored if time_range is set)

Returns: Object with data (activity array) and paging. Each activity record contains who made the change, what was changed, when, and the specific details.

• actor_name (string): Name of the user who made the change
• object_type (string): Type of object: AD, ADSET, CAMPAIGN, ACCOUNT, IMAGE, REPORT, etc.
• translated_event_type (string): Human-readable description, e.g., 'ad created', 'campaign budget updated'
• event_time (string): Timestamp of the event
• changed_data (string): JSON detailing what changed

Use meta_ads_fetch_pagination_url with paging.next to retrieve additional pages.

Examples:

• Use when: "What changes were made to ad set 23843211234567 this month?"
• Use when: "Show me the targeting change history for this ad set"

Get detailed information about a specific Meta ad account.

Args:

• act_id (string): The ad account ID prefixed with 'act_', e.g., 'act_1234567890'
• fields (string[]): Optional. Fields to retrieve. If omitted, defaults to: name, business_name, age, account_status, balance, amount_spent, attribution_spec, account_id, business, business_city, brand_safety_content_filter_levels, currency, created_time, id.

Returns: Object with the requested ad account fields. Key fields:

• id (string): Ad account ID
• name (string): Account display name
• account_status (number): Status code (1=ACTIVE, 2=DISABLED, 3=UNSETTLED, etc.)
• currency (string): Account currency code (e.g., 'USD')
• balance (string): Current account balance
• amount_spent (string): Total lifetime spend

Examples:

• Use when: "Get details for ad account act_123456"
• Use when: "What is the currency and balance of my ad account?"

Retrieve detailed information about a specific Meta ad.

Args:

• ad_id (string): Ad ID, e.g., '23843211234567'
• fields (string[]): Fields per ad. Common: id, name, account_id, adset_id, campaign_id, status, effective_status, configured_status, creative, bid_amount, bid_type, created_time, updated_time, targeting, conversion_specs, recommendations, preview_shareable_link

Returns: Object with the requested ad fields.

Examples:

• Use when: "Get details for ad 23843211234567"
• Use when: "What creative and status does this ad have?"

Retrieve detailed information about a specific Meta ad creative.

Args:

• creative_id (string): Ad creative ID, e.g., '23842312323312'
• fields (string[]): Fields to retrieve. Available: id, name, account_id, actor_id, adlabels, asset_feed_spec, authorization_category, body, call_to_action_type, effective_authorization_category, effective_instagram_media_id, effective_object_story_id, image_hash, image_url, instagram_permalink_url, instagram_story_id, instagram_user_id, link_url, object_id, object_story_id, object_story_spec, object_type, object_url, platform_customizations, product_set_id, status, template_url, thumbnail_url, title, url_tags, use_page_actor_override, video_id
• thumbnail_width (number): Width of the thumbnail image in pixels (default: 64)
• thumbnail_height (number): Height of the thumbnail image in pixels (default: 64)

Returns: Object with the requested creative fields.

Examples:

• Use when: "Get the body text, title, and image URL for creative 23842312323312"
• Use when: "What is the call-to-action type and status of this creative?"
• Use when: "Get a larger thumbnail (300x200) for this creative"

Retrieve the ad creatives associated with a specific Meta ad.

Args:

• ad_id (string): Ad ID to retrieve creatives for, e.g., '23843211234567'
• fields (string[]): Fields to retrieve. Available: id, name, account_id, actor_id, adlabels, asset_feed_spec, authorization_category, body, call_to_action_type, effective_authorization_category, effective_instagram_media_id, effective_object_story_id, image_hash, image_url, instagram_permalink_url, instagram_story_id, instagram_user_id, link_url, object_id, object_story_id, object_story_spec, object_type, object_url, platform_customizations, product_set_id, status, template_url, thumbnail_url, title, url_tags, use_page_actor_override, video_id
• limit (number): Maximum creatives per page (default: 25)
• after / before (string): Pagination cursors from response.paging.cursors
• date_format (string): Date format: 'U' for Unix timestamp, 'Y-m-d H:i:s' for MySQL datetime

Returns: Object with data (creative array) and paging. Use meta_ads_fetch_pagination_url with paging.next for more results.

Examples:

• Use when: "What creatives are used by ad 23843211234567?"
• Use when: "Get the image URLs and titles for all creatives on this ad"

Retrieve ad images belonging to a Meta ad account.

Useful for auditing image assets, finding images by hash or name, and checking image dimensions and status.

Args:

• act_id (string): Ad account ID prefixed with 'act_', e.g., 'act_1234567890'
• fields (string[]): Fields to retrieve. Available: id, account_id, created_time, creatives, hash, height, is_associated_creatives_in_adgroups, name, original_height, original_width, permalink_url, status, updated_time, url, url_128, width
• hashes (string[]): Filter by specific image hashes
• name (string): Filter images by name (partial match)
• minwidth (number): Minimum image width in pixels
• minheight (number): Minimum image height in pixels
• limit (number): Results per page (1-100, default: 25)
• after / before (string): Pagination cursors

Returns: Object with data (image array) and paging. Each image contains URL, dimensions, hash, and status. Use meta_ads_fetch_pagination_url with paging.next for more results.

Examples:

• Use when: "List all images in my ad account"
• Use when: "Find images with hashes abc123 and def456"
• Use when: "Show images wider than 1000px"

Retrieve detailed performance insights for a specific Meta ad.

Fetches performance metrics for an individual ad, such as impressions, clicks, conversions, video views, etc.

Args:

• ad_id (string): Ad ID, e.g., '6123456789012'
• fields (string[]): Metrics to retrieve. Common: ad_name, adset_name, campaign_name, impressions, clicks, spend, ctr, cpc, cpm, reach, frequency, actions, conversions, cost_per_action_type, inline_link_clicks, video_p25_watched_actions
• date_preset (string): Relative time range preset (default: last_30d)
• time_range (object): Custom range {'since':'YYYY-MM-DD','until':'YYYY-MM-DD'}
• level (string): Aggregation level, should be 'ad' (default: ad)
• breakdowns (string[]): Segment by: age, gender, country, publisher_platform, impression_device, platform_position, device_platform, etc.
• See full parameter list in inputSchema

Returns: Object with:

• data (array): List of insight records with requested metrics
• paging (object): Pagination cursors. Use meta_ads_fetch_pagination_url with paging.next to get more results

Pagination note: When response contains paging.next, use meta_ads_fetch_pagination_url to retrieve additional pages automatically.

Generate preview links or embed HTML for a Meta ad in various ad formats and placements.

Allows you to see how an ad looks across different placements (Facebook feed, Instagram, Stories, etc.) before or after publishing.

Args:

• ad_id (string): Ad ID to preview, e.g., '23843211234567'
• ad_format (string): Preview format. Options: DESKTOP_FEED_STANDARD, MOBILE_FEED_STANDARD, MOBILE_FEED_BASIC, MOBILE_INTERSTITIAL, MOBILE_BANNER, MOBILE_MEDIUM_RECTANGLE, MOBILE_FULLWIDTH, RIGHT_COLUMN_STANDARD, INSTAGRAM_STANDARD, INSTAGRAM_STORY, AUDIENCE_NETWORK_OUTSTREAM_VIDEO, AUDIENCE_NETWORK_INSTREAM_VIDEO, FACEBOOK_STORY_MOBILE, MESSENGER_MOBILE_INBOX_MEDIA, SUGGESTED_VIDEO_MOBILE, WATCH_FEED_MOBILE, FACEBOOK_REELS_MOBILE, INSTAGRAM_REELS
• locale (string): Locale for the preview, e.g., 'en_US'
• start_date (string): Preview start date for scheduled ads (UNIX timestamp)
• end_date (string): Preview end date for scheduled ads (UNIX timestamp)

Returns: Object with data array. Each item contains:

• body (string): HTML iframe embed code for the preview
• encoded_creative_id (string): Encoded creative ID

Examples:

• Use when: "Show me how ad 23843211234567 looks on Instagram"
• Use when: "Preview this ad in desktop feed format"
• Use when: "Generate previews for all placements of this ad"

Get video details (source URL, thumbnail, title, duration) for a Meta ad video. Provide either ad_id (server resolves the video_id from the ad's creative) or video_id directly. Pass act_id when available — the /act_X/advideos edge avoids permission errors (#10 / #33) that hit the bare /{video_id} node for BM-shared or page-owned videos.

Retrieve performance insights for a Meta ad account.

Fetches metrics like impressions, reach, clicks, spend, conversions, and more for an entire ad account. Supports time range definitions, demographic breakdowns, and attribution settings.

Args:

• act_id (string): Ad account ID prefixed with 'act_', e.g., 'act_1234567890'
• fields (string[]): Metrics to retrieve. Common: impressions, reach, clicks, spend, ctr, cpc, cpm, cpp, frequency, actions, conversions, cost_per_action_type
• date_preset (string): Relative time range preset (default: last_30d)
• time_range (object): Custom range {'since':'YYYY-MM-DD','until':'YYYY-MM-DD'}
• level (string): Aggregation level: account, campaign, adset, ad (default: account)
• breakdowns (string[]): Segment by: age, gender, country, impression_device, publisher_platform, etc.
• See full parameter list in inputSchema

Returns: Object with:

• data (array): List of insight records with requested metrics
• paging (object): Pagination cursors. Use meta_ads_fetch_pagination_url with paging.next to get more results

Pagination note: When response contains paging.next, use meta_ads_fetch_pagination_url to retrieve additional pages automatically.

Retrieve all ad creatives belonging to a specific Meta ad account.

Useful for auditing all creative assets, finding creatives by status, or reviewing creative content across the account.

Args:

• act_id (string): Ad account ID prefixed with 'act_', e.g., 'act_1234567890'
• fields (string[]): Fields to retrieve. Available: id, name, account_id, actor_id, adlabels, asset_feed_spec, authorization_category, body, call_to_action_type, effective_authorization_category, effective_instagram_media_id, effective_object_story_id, image_hash, image_url, instagram_permalink_url, instagram_story_id, instagram_user_id, link_url, object_id, object_story_id, object_story_spec, object_type, object_url, platform_customizations, product_set_id, status, template_url, thumbnail_url, title, url_tags, use_page_actor_override, video_id
• effective_status (string[]): Filter by status: ACTIVE, DELETED, IN_PROCESS, WITH_ISSUES
• filtering (object[]): Additional filter objects with field, operator, value
• limit (number): Results per page (1-100, default: 25)
• after / before (string): Pagination cursors

Returns: Object with data (creative array) and paging. Use meta_ads_fetch_pagination_url with paging.next for more results.

Examples:

• Use when: "List all active creatives in my ad account"
• Use when: "Show all creatives with issues in act_123456"

Retrieve all ads from a specific Meta ad account with filtering and pagination.

Args:

• act_id (string): Ad account ID prefixed with 'act_', e.g., 'act_1234567890'
• fields (string[]): Fields per ad. Common: id, name, account_id, adset_id, campaign_id, status, effective_status, configured_status, creative, bid_amount, bid_type, created_time, updated_time, targeting, conversion_specs, recommendations, preview_shareable_link
• effective_status (string[]): Filter by status: ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED, IN_PROCESS, WITH_ISSUES
• filtering (object[]): Additional filter objects with field, operator, value
• limit (number): Results per page (1-100, default: 25)
• after / before (string): Pagination cursors
• date_preset / time_range: Date filter
• updated_since (number): Unix timestamp — return ads updated since this time

Returns: Object with data (ad array) and paging. Use meta_ads_fetch_pagination_url with paging.next for more results.

Retrieve all ads belonging to a specific Meta ad set with filtering and pagination.

Args:

• adset_id (string): Ad set ID, e.g., '23843211234567'
• fields (string[]): Fields per ad. Common: id, name, account_id, adset_id, campaign_id, status, effective_status, configured_status, creative, bid_amount, bid_type, created_time, updated_time, targeting, conversion_specs, recommendations, preview_shareable_link
• effective_status (string[]): Filter by status: ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, IN_PROCESS, WITH_ISSUES
• filtering (object[]): Filter objects. Operators: EQUAL, NOT_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN_RANGE, NOT_IN_RANGE, CONTAIN, NOT_CONTAIN, IN, NOT_IN, EMPTY, NOT_EMPTY
• limit (number): Results per page (1-100, default: 25, max: 100)
• after / before (string): Pagination cursors
• date_format (string): Date format for response

Returns: Object with data (ad array) and paging. Use meta_ads_fetch_pagination_url with paging.next for more results.

Retrieve all ads belonging to a specific Meta campaign with filtering and pagination.

Args:

• campaign_id (string): Campaign ID, e.g., '23843xxxxx'
• fields (string[]): Fields per ad. Common: id, name, account_id, adset_id, campaign_id, status, effective_status, configured_status, creative, bid_amount, bid_type, created_time, updated_time, targeting, conversion_specs, recommendations, preview_shareable_link
• effective_status (string[]): Filter by status: ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, ADSET_PAUSED, ARCHIVED, IN_PROCESS, WITH_ISSUES
• filtering (object[]): Additional filter objects with field, operator, value
• limit (number): Results per page (1-100, default: 25)
• after / before (string): Pagination cursors

Returns: Object with data (ad array) and paging. Use meta_ads_fetch_pagination_url with paging.next for more results.

Retrieve detailed information about a specific Meta ad set.

Args:

• adset_id (string): Ad set ID, e.g., '23843211234567'
• fields (string[]): Fields per ad set. Common: id, name, account_id, campaign_id, status, effective_status, daily_budget, lifetime_budget, budget_remaining, bid_amount, bid_strategy, billing_event, optimization_goal, targeting, start_time, end_time, created_time, updated_time, pacing_type, destination_type

Returns: Object with the requested ad set fields.

Examples:

• Use when: "Get the targeting and budget for ad set 23843211234567"
• Use when: "What is the optimization goal and status of this ad set?"

Retrieve performance insights for a specific Meta ad set.

Provides advertising statistics for an ad set, useful for analyzing performance across its child ads.

Args:

• adset_id (string): Ad set ID, e.g., '6123456789012'
• fields (string[]): Metrics to retrieve. Common: adset_name, campaign_name, impressions, clicks, spend, ctr, reach, actions, cpc, cpm, cpp, cost_per_action_type
• date_preset (string): Relative time range preset (default: last_30d)
• time_range (object): Custom range {'since':'YYYY-MM-DD','until':'YYYY-MM-DD'}
• level (string): Aggregation level: adset, ad (default: adset)
• breakdowns (string[]): Segment by: age, gender, country, publisher_platform, impression_device, platform_position, etc.
• See full parameter list in inputSchema

Returns: Object with:

• data (array): List of insight records with requested metrics
• paging (object): Pagination cursors. Use meta_ads_fetch_pagination_url with paging.next to get more results

Pagination note: When response contains paging.next, use meta_ads_fetch_pagination_url to retrieve additional pages automatically.

Retrieve all ad sets from a specific Meta ad account with filtering and pagination.

Args:

• act_id (string): Ad account ID prefixed with 'act_', e.g., 'act_1234567890'
• fields (string[]): Fields per ad set. Common: id, name, account_id, campaign_id, status, effective_status, daily_budget, lifetime_budget, budget_remaining, bid_amount, bid_strategy, billing_event, optimization_goal, targeting, start_time, end_time, created_time, updated_time, pacing_type, destination_type
• effective_status (string[]): Filter by status: ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, WITH_ISSUES
• filtering (object[]): Additional filter objects, e.g., [{field: 'daily_budget', operator: 'GREATER_THAN', value: 1000}]
• limit (number): Results per page (1-100, default: 25)
• after / before (string): Pagination cursors
• date_preset / time_range: Date filter
• updated_since (number): Unix timestamp — return ad sets updated since this time
• date_format (string): Date format for response

Returns: Object with data (ad set array) and paging. Use meta_ads_fetch_pagination_url with paging.next for more results.

Retrieve all ad sets belonging to a specific Meta campaign with filtering and pagination.

Args:

• campaign_id (string): Campaign ID, e.g., '23843xxxxx'
• fields (string[]): Fields per ad set. Common: id, name, account_id, campaign_id, status, effective_status, daily_budget, lifetime_budget, budget_remaining, bid_amount, bid_strategy, billing_event, optimization_goal, targeting, start_time, end_time, created_time, updated_time, pacing_type, destination_type
• effective_status (string[]): Filter by status: ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, ARCHIVED, WITH_ISSUES
• filtering (object[]): Additional filter objects, e.g., [{field: 'optimization_goal', operator: 'IN', value: ['OFFSITE_CONVERSIONS', 'VALUE']}]
• limit (number): Results per page (1-100, default: 25)
• after / before (string): Pagination cursors
• date_format (string): Date format for response

Returns: Object with data (ad set array) and paging. Use meta_ads_fetch_pagination_url with paging.next for more results.

Retrieve information for multiple Meta ad sets in a single API call (batch lookup).

Efficient when you need data for several ad sets at once.

Args:

• adset_ids (string[]): List of ad set IDs to retrieve, e.g., ['23843211234567', '23843211234568']
• fields (string[]): Fields per ad set. Common: id, name, account_id, campaign_id, status, effective_status, daily_budget, lifetime_budget, budget_remaining, bid_amount, bid_strategy, billing_event, optimization_goal, targeting, start_time, end_time, created_time, updated_time, pacing_type, destination_type
• date_format (string): Date format: 'U' for Unix timestamp, 'Y-m-d H:i:s' for MySQL datetime

Returns: Object where keys are ad set IDs and values are the corresponding ad set details.

Examples:

• Use when: "Get details for ad sets 23843211234567, 23843211234568, and 23843211234569"

Retrieve detailed information about a specific Meta ad campaign.

Args:

• campaign_id (string): Campaign ID, e.g., '23843xxxxx'
• fields (string[]): Fields to retrieve. Available: id, name, account_id, objective, status, effective_status, configured_status, daily_budget, lifetime_budget, budget_remaining, spend_cap, bid_strategy, buying_type, created_time, updated_time, start_time, stop_time, special_ad_categories, pacing_type, promoted_object, issues_info, recommendations
• date_format (string): Date format: 'U' for Unix timestamp, 'Y-m-d H:i:s' for MySQL datetime, default: ISO 8601

Returns: Object with the requested campaign fields.

Examples:

• Use when: "Get details for campaign 23843xxxxx"
• Use when: "What is the objective and status of my campaign?"

Retrieve performance insights for a specific Meta ad campaign.

Fetches advertising statistics for a campaign, allowing analysis of metrics like impressions, clicks, conversions, spend, etc.

Args:

• campaign_id (string): Campaign ID, e.g., '23843xxxxx'
• fields (string[]): Metrics to retrieve. Common: campaign_name, impressions, clicks, spend, ctr, reach, actions, objective, cpc, cpm, date_start, date_stop
• date_preset (string): Relative time range preset (default: last_30d)
• time_range (object): Custom range {'since':'YYYY-MM-DD','until':'YYYY-MM-DD'}
• level (string): Aggregation level: campaign, adset, ad (default: campaign)
• breakdowns (string[]): Segment by: age, gender, country, publisher_platform, impression_device, etc.
• See full parameter list in inputSchema

Returns: Object with:

• data (array): List of insight records with requested metrics
• paging (object): Pagination cursors. Use meta_ads_fetch_pagination_url with paging.next to get more results

Pagination note: When response contains paging.next, use meta_ads_fetch_pagination_url to retrieve additional pages automatically.

Retrieve all campaigns from a specific Meta ad account with filtering and pagination.

Args:

• act_id (string): Ad account ID prefixed with 'act_', e.g., 'act_1234567890'
• fields (string[]): Fields per campaign. Common: id, name, objective, effective_status, created_time, daily_budget, lifetime_budget, budget_remaining
• effective_status (string[]): Filter by status: ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, ARCHIVED, WITH_ISSUES
• objective (string[]): Filter by objective: APP_INSTALLS, BRAND_AWARENESS, CONVERSIONS, EVENT_RESPONSES, LEAD_GENERATION, LINK_CLICKS, MESSAGES, PAGE_LIKES, POST_ENGAGEMENT, PRODUCT_CATALOG_SALES, REACH, VIDEO_VIEWS
• filtering (object[]): Additional filter objects with field, operator, value
• limit (number): Results per page (1-100, default: 25)
• after / before (string): Pagination cursors
• date_preset / time_range: Date filter for campaigns
• updated_since (number): Return campaigns updated since this Unix timestamp
• is_completed (boolean): True = only completed, False = only active, null = both
• special_ad_categories (string[]): Filter by: EMPLOYMENT, HOUSING, CREDIT, ISSUES_ELECTIONS_POLITICS, NONE
• include_drafts (boolean): Include draft campaigns if true
• date_format (string): Date format for response

Returns: Object with data (campaign array) and paging. Use meta_ads_fetch_pagination_url with paging.next for more results.

Look up a single image in an ad account's image library by hash. Returns the CDN url, dimensions, name, and status — useful when you only have the hash (e.g., from upload_ad_image or a creative's object_story_spec.link_data.image_hash) and need the URL.

Given a seed list of interest names, return related/suggested interests.

Args:

• interest_list (string[]): Seed interest names, e.g., ["Basketball", "Soccer"]
• limit (number, optional): Max suggestions (default 25)

List all ad accounts associated with the authenticated Facebook user.

Returns account names and IDs. When the response contains a paging.next URL, use meta_ads_fetch_pagination_url to retrieve additional pages.

Returns: Object with adaccounts.data array, each containing:

• id (string): Ad account ID prefixed with 'act_' (e.g., 'act_1234567890')
• name (string): Display name of the ad account

Examples:

• Use when: "Show me all my ad accounts"
• Use when: "What ad accounts do I have access to?"

List available behavior targeting options.

Args:

• limit (number, optional): Max results (default 50)

List demographic targeting options. Pass demographic_class to scope the results (default: 'demographics'). Other valid classes: 'life_events', 'industries', 'income', 'family_statuses', 'user_device', 'user_os'.

Search Meta's geographic targeting catalog by query string. Returns location keys to use in targeting.geo_locations.

Args:

• q (string): Search term (e.g., "New York", "Japan")
• location_types (string[], optional): Filter by types: 'country', 'region', 'city', 'zip', 'geo_market', 'electoral_district'.
• limit (number, optional): Max results (default 25)

Search Meta's interest targeting catalog by keyword. Returns interest IDs suitable for use in an ad set's targeting.flexible_spec.

Args:

• q (string): Search term (e.g., "baseball", "cooking", "travel")
• limit (number, optional): Max results (default 25)

Returns: { data: [{ id, name, audience_size_lower_bound, audience_size_upper_bound, path, topic }] }

Search the user's pages by a case-insensitive substring of name or username.

Internally fetches /me/accounts then filters client-side. Meta's Graph API does not expose a server-side name filter on /me/accounts.

Args:

• search_term (string): Substring to match against page name or username.