> This page is for Agent Handler. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # Meta Ads **Authentication:** OAuth or access token. See [Magic Link](/merge-agent-handler/features/magic-link) for the runtime auth flow, or [Application credentials](/merge-agent-handler/admin-setup/add-oauth-credentials) to bring your own OAuth app. ## Sample use cases * List the active campaigns in ad account `act_123456789` with their daily budgets * Create an ad creative and an ad for the `Spring Sale` ad set * Add a list of customer emails to the `Past Purchasers` custom audience ## Available Tools #### add_custom_audience_users Add users to a customer-list audience by uploading hashed personal data. Requires custom_audience_id (from list_custo... #### cancel_ad_study Cancel (delete) an ad study by id. Use list_ad_studies to find study ids. This is the inverse of create_ad_study. #### connect_catalog_event_source Connect one or more event sources (pixels, apps, offline sets) to a catalog for signal matching. Requires catalog_id... #### create_ad Create an ad in an ad set. Requires account_id (from list_ad_accounts), name, adset_id (from list_ad_sets), creative... #### create_ad_creative Create an ad creative under an ad account. Requires account_id (from list_ad_accounts) and name; optionally title, bo... #### create_ad_set Create an ad set under a campaign. Requires account_id (from list_ad_accounts), name, campaign_id (from list_campaign... #### create_ad_study Create an ad study (A/B test or conversion lift). Requires business_id (numeric id from Business settings, NOT an ad... #### create_campaign Create a campaign under an ad account. Requires account_id (from list_ad_accounts), name, objective, special_ad_categ... #### create_custom_audience Create a custom audience. Requires account_id (from list_ad_accounts) and name; a CUSTOM (customer-file) audience als... #### create_feed_rule Create a supplementary rule that maps or transforms an attribute on a feed. Requires feed_id (from list_product_feeds... #### create_feed_upload Start an upload session that fetches a feed file from a URL. Requires feed_id (from list_product_feeds) and url; set... #### create_product Add a product to a catalog. Requires catalog_id (from list_product_catalogs), retailer_id (your SKU), name, price (in... #### create_product_catalog Create a product catalog under a Business Manager. Requires business_id (numeric id from Business settings) and name... #### create_product_feed Register a product feed on a catalog. Requires catalog_id (from list_product_catalogs) and name; optionally feed_type... #### create_product_set Create a product set in a catalog. Requires catalog_id (from list_product_catalogs) and name; optionally a structured... #### delete_ad Delete an ad by id. Use list_ads to find ad ids. This removes the ad and stops its delivery. #### delete_ad_creative Delete an ad creative by id. Use list_ad_creatives to find creative ids. #### delete_ad_set Delete an ad set by id. Use list_ad_sets to find ad set ids. This removes the ad set and stops delivery of its ads. #### delete_campaign Delete a campaign by id. Use list_campaigns to find campaign ids. This removes the campaign and its delivery. #### delete_custom_audience Delete a custom audience by id. Use list_custom_audiences to find audience ids. Inverse of create_custom_audience. #### delete_feed_rule Delete a feed transformation rule by id without affecting the feed or products. Use list_feed_rules to find rule ids... #### delete_product Delete a product from a catalog by id. Use list_products to find product ids. Inverse of create_product. #### delete_product_feed Delete a product feed and its schedule by id; products it supplied are removed asynchronously. Use list_product_feeds... #### delete_product_set Delete a product set by id; products remain in the catalog. Use list_product_sets to find ids. Set allow_live_product... #### disconnect_catalog_event_source Disconnect one or more event sources from a catalog to stop signal matching. Requires catalog_id (from list_product_c... #### generate_ad_preview Render a preview of an ad or creative in a specific placement (Feed, Story, Reels, etc.). Requires account_id (from l... #### get_ad_study Get a single ad study by id, with type, status, cells, and results. Works for both A/B tests and lift studies. Use li... #### get_campaign Get a single campaign by id, with status, objective, and budgets. Use list_campaigns to find campaign ids. #### get_custom_audience Get a single custom audience by id, with size, status, and subtype. Use list_custom_audiences to find audience ids. #### get_dataset Get a dataset (pixel) node: metadata, Conversions API configuration, and pixel settings. Use list_datasets to find pi... #### get_dataset_stats Get a dataset's event volume over a time window, optionally broken down by device or event source. Use list_datasets... #### get_product Get a single product by id, with name, price, availability, and imagery. Use list_products to find product ids. #### get_product_catalog Get a single product catalog by id, with name, vertical, product/feed counts, and owning business. Use list_product_c... #### get_product_feed Get a single product feed's configuration by id: URL, schedule, format, and status. Use list_product_feeds to find fe... #### get_product_set Get a single product set by id, with its filter rule and match count. Use list_product_sets to find product set ids. #### list_activities List activity log entries for an ad account (who changed what, when). Pass account_id from list_ad_accounts. Filter b... #### list_ad_accounts List the ad accounts the token can access, with id (act_number), name, currency, and balance. Start here to get an ac... #### list_ad_creatives List ad creatives under an ad account, each with its id for attaching to a new ad. Pass account_id from list_ad_accou... #### list_ad_images List ad images uploaded to an ad account, each with its hash (used to reference it in a creative). Pass account_id fr... #### list_ad_sets List ad sets under an ad account, each with its campaign_id for client-side scoping. Pass account_id from list_ad_acc... #### list_ad_studies List the ad studies (A/B tests and lift studies) that impact an ad account. Pass account_id from list_ad_accounts. Pa... #### list_ad_videos List ad videos uploaded to an ad account, each with id, title, and length. Pass account_id from list_ad_accounts. Fil... #### list_ads List ads under an ad account, each with its adset_id and campaign_id for client-side scoping. Pass account_id from li... #### list_campaigns List campaigns under an ad account, with status, objective, and budgets. Pass account_id from list_ad_accounts. Filte... #### list_catalog_data_sources List the data sources (feeds, uploads, API sources) attached to a product catalog. Use list_product_catalogs to find... #### list_catalog_diagnostics List diagnostics (errors, warnings, opportunities) on a product catalog that may affect ad delivery. Use list_product... #### list_catalog_event_sources List the event sources (pixels, apps, offline conversion sets) connected to a product catalog. Pass catalog_id from l... #### list_custom_audiences List custom audiences on an ad account, each with name, subtype, and approximate size. Pass account_id from list_ad_a... #### list_custom_conversions List custom conversions defined on an ad account, each with name, rule, and event type. Pass account_id from list_ad\_... #### list_datasets List datasets (pixels) on an ad account, each with name and last-fired time. Pass account_id from list_ad_accounts. P... #### list_feed_rules List the supplementary rules applied to a product feed. Pass feed_id from list_product_feeds. Page with limit + after. #### list_feed_uploads List upload sessions for a product feed, with status and error counts. Pass feed_id from list_product_feeds. Page wit... #### list_instagram_accounts List Instagram Business/Creator accounts linked to an ad account, each with id and username. Pass account_id from lis... #### list_instagram_media List recent media (posts, reels, stories) on an Instagram Business/Creator account. Pass ig_user_id from list_instagr... #### list_product_catalogs List product catalogs owned by a Business Manager, with name, vertical, and product count. Pass business_id (the nume... #### list_product_feeds List the product feeds registered on a catalog, each with name and product count. Pass catalog_id from list_product_c... #### list_product_set_products List the products contained in a product set. Use list_product_sets to find product set ids. Page with limit + after. #### list_product_sets List product sets in a catalog, each with name and product count. Pass catalog_id from list_product_catalogs. Page wi... #### list_products List or search products in a product catalog. Pass catalog_id from list_product_catalogs. Pass a structured filter ob... #### list_promote_pages List the Facebook Pages that have been used for ads on an ad account, each with id and name. Pass account_id from lis... #### remove_custom_audience_users Remove users from a customer-list audience by uploading hashed personal data to match. Requires custom_audience_id (f... #### search_ad_library Search the public Meta Ad Library for competitive research. Requires ad_reached_countries and at least one of search\_... #### send_dataset_events Send server events to a dataset via the Conversions API (POST //events). Requires pixel_id (from list_datasets) and d... #### update_ad_study Edit an existing ad study's name, description, end time, or cells. Use list_ad_studies to find study ids. To cancel a... #### update_campaign Update a campaign by id (Meta uses POST, not PATCH). Change name, status, budgets, bid_strategy, or special_ad_catego... #### update_custom_audience Update a custom audience's name, description, or website rule. Use list_custom_audiences to find audience ids. Meta u... #### update_dataset Update a dataset (pixel) setting: name, automatic advanced matching, or data-use. Use list_datasets to find pixel ids... #### update_product Update a product's fields (name, price, availability, brand, imagery). Use list_products to find product ids. Meta us... #### update_product_catalog Update a product catalog's name or default/fallback image URLs. Use list_product_catalogs to find catalog ids. Meta u... #### update_product_feed Update a product feed's name, currency default, or fetch schedules. Use list_product_feeds to find feed ids. Meta use... #### update_product_set Update a product set's name, filter, or retailer id. Use list_product_sets to find product set ids. Meta uses POST (n...