create_meta_video_campaign

Description

User wants to create a Meta (Facebook/Instagram) video ad campaign. REQUIRED: You MUST call `select_meta_campaign_type` first and complete ALL phases it describes (audience targeting research via `search_meta_targeting`/`browse_meta_targeting`, asset discovery via `discover_meta_assets`, and user approval) BEFORE calling this tool. IMPORTANT: This tool creates REAL campaigns that will spend money once activated. Campaign is created in PAUSED status for review. DO NOT USE for image ads - use `create_meta_image_campaign` instead. DO NOT USE for carousel - use `create_meta_carousel_campaign` instead. This tool creates a complete Meta video campaign with: 1. Campaign (objective, budget) 2. Ad Set (targeting, placements, schedule) 3. Video Upload (handles large files with chunked upload) 4. Ad Creative (video, text, CTA) 5. Ad (linking creative to ad set) When to use this tool: - "Create a Facebook video ad campaign" - "Launch an Instagram video ad" - "Set up a Meta Reels campaign" - "Create an ad with this video" Required Parameters: - campaign_name: Name for the campaign - budget_daily: Daily budget in USD (min $1, recommend $5-20 for testing) - primary_text: Main ad text (recommended 125 chars for optimal display, longer text shows with "See More") - landing_page_url: Where users go when clicking Video Source (choose ONE): - video_url: Public video URL (will be uploaded during creation) - existing_video_id: Existing Meta video ID (for reusing previously uploaded videos) Optional Parameters: - facebook_page_id: Auto-detected from connected account - instagram_account_id: Enable Instagram placements - thumbnail_url: Custom thumbnail image (Meta auto-generates if not provided) - headline: Headline below video (optional for video ads) - description: Description text (max 255 chars, recommended 30) - call_to_action: WATCH_MORE (default), LEARN_MORE, SHOP_NOW, etc. - objective: OUTCOME_TRAFFIC (default), OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_AWARENESS - locations: Country codes (default: ['US']) - age_min/age_max: Age targeting (18-65) - genders: ['male'], ['female'], or null for all - optimize_for_reels: true for vertical (9:16) videos - pixel_id: Meta Pixel ID for conversion tracking (required for OUTCOME_SALES) - pixel_event_name: Conversion event (PURCHASE, LEAD, etc.) Video Specifications: - Formats: MP4, MOV (recommended: MP4 H.264) - Max size: 4GB (recommended under 1GB) - Duration: 1 sec - 240 min (recommended 15-60 sec) - Feed: 1:1 or 4:5 aspect ratio - Stories/Reels: 9:16 aspect ratio After Creation — IMPORTANT: - This tool created 1 campaign + 1 ad set + 1 ad. - To add MORE ad sets (different targeting, audiences, or formats), use `add_meta_ad_set` with the returned campaign_id - To add MORE ads to the same ad set (A/B test copy/creative), use `add_meta_ad` with the returned ad_set_id - NEVER call this create tool again for the same campaign — that creates a SEPARATE campaign

Request body

All tool arguments are wrapped in an arguments object.

Field	Type	Description
`campaign_name`	`string` required	Campaign name (will be automatically suffixed with timestamp for uniqueness)
`objective`	`string` optional	Campaign objective. Options: 'OUTCOME_TRAFFIC' (website clicks), 'OUTCOME_SALES' (conversions), 'OUTCOME_LEADS' (lead forms), 'OUTCOME_AWARENESS' (reach), 'OUTCOME_ENGAGEMENT'. Default: OUTCOME_TRAFFIC default: `"OUTCOME_TRAFFIC"`
`budget_daily`	`number` optional	Daily budget in account currency (minimum $1/day, recommended $5-20/day for testing). Mutually exclusive with budget_lifetime — provide exactly one.
`budget_lifetime`	`number` optional	Lifetime budget in account currency (total spend over campaign duration). REQUIRES end_time to be set. Mutually exclusive with budget_daily — provide exactly one.
`end_time`	`string` optional	Campaign/ad set end date in ISO format (e.g. '2026-04-30T23:59:59'). REQUIRED when using budget_lifetime. Optional with budget_daily.
`video_url`	`string` optional	Public video URL to upload. Video will be uploaded during campaign creation. Supports MP4, MOV formats. Max 4GB, recommended under 1GB. Mutually exclusive with existing_video_id.
`existing_video_id`	`string` optional	Existing Meta video ID from your Ad Library. Use this to REUSE videos already uploaded to Meta. Mutually exclusive with video_url.
`thumbnail_url`	`string` optional	Optional custom thumbnail image URL. If not provided, Meta will auto-generate thumbnails from video.
`facebook_page_id`	`string` optional	Facebook Page ID for the ad. Usually auto-detected from your connected account. Only provide if you have multiple pages and want to use a specific one.
`primary_text`	`string` optional	REQUIRED (this OR `primary_texts`). Primary ad text (max 2200 characters, recommended 125 or less for optimal display). Ask the user for it before calling this tool. Supports emojis, line breaks (\n), and bullet points (e.g. '🔥 Limited Offer!\n\n✅ Free Shipping\n✅ 30-Day Returns'). This is the main message that appears above the video. ⚠️ If the user supplies MORE THAN ONE primary text variation, do NOT pick one and do NOT use this field — put ALL of them in the `primary_texts` array instead (Meta tests the combinations as Dynamic Creative in a single ad). Use this singular field only for a single body text. Exactly one of `primary_text` or `primary_texts` is required.
`headline`	`string` optional	Headline text (max 255 characters, recommended 40). Optional for video ads. Appears below the video on some placements. ⚠️ If the user supplies MORE THAN ONE headline variation, put ALL of them in the `headlines` array field instead of picking one.
`landing_page_url`	`string` required	REQUIRED. Landing page URL where users will be directed when clicking the ad. Must be HTTPS. Ask the user for it before calling this tool.
`call_to_action`	`string` optional	Call-to-action button. Options: 'WATCH_MORE' (default for video), 'LEARN_MORE', 'SHOP_NOW', 'SIGN_UP', 'DOWNLOAD', 'BOOK_TRAVEL', 'CONTACT_US'. Default: WATCH_MORE default: `"WATCH_MORE"`
`description`	`string` optional	Optional description text (max 255 characters, recommended 30). Appears under the headline on some placements. If the user supplies more than one description variation, use the `descriptions` array field instead.
`instagram_account_id`	`string` optional	Instagram account ID for Instagram placements. If not provided, ad will run on Facebook only.
`pixel_id`	`string` optional	Meta Pixel ID for conversion tracking. Required for OUTCOME_SALES campaigns. Use list_meta_pixels to find available pixels for your ad account.
`pixel_event_name`	`string` optional	Conversion event to optimize for when pixel_id is provided. Options: PURCHASE, LEAD, COMPLETE_REGISTRATION, ADD_TO_CART, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, SEARCH, CONTENT_VIEW, OTHER. Use OTHER with custom_conversion_id for custom pixel events. Default: PURCHASE
`custom_conversion_id`	`string` optional	Custom conversion ID for optimizing towards a specific custom conversion. When provided, pixel_event_name is ignored — Meta infers the event type from the custom conversion. Get available custom conversions from your Meta Events Manager.
`destination_type`	`string` optional	Override the ad set destination type. By default, OUTCOME_LEADS uses ON_AD (Meta lead forms) and OUTCOME_TRAFFIC uses WEBSITE. Set to 'WEBSITE' for OUTCOME_LEADS campaigns that track conversions on your website via Meta Pixel instead of using Meta's built-in lead form. Options: WEBSITE, ON_AD, WEBSITE_AND_ON_AD. Only provide when overriding the default.
`campaign_budget_optimization`	`boolean` optional	Enable Advantage Campaign Budget (CBO). When true, the daily budget is set at the campaign level and Meta automatically distributes it across ad sets. When false (default), each ad set manages its own budget. default: `false`
`daily_min_spend_target`	`number` optional	CBO only: minimum daily spend for this ad set in account currency. Meta will try to spend at least this amount on this ad set each day.
`daily_spend_cap`	`number` optional	CBO only: maximum daily spend cap for this ad set in account currency. Meta will not spend more than this on this ad set each day.
`locations`	`array` optional	Location targeting. Accepts country codes (['US', 'CA']) OR location objects from search_meta_targeting ([{'key': '2421836', 'type': 'city', 'radius': 25, 'distance_unit': 'mile'}]). For city/region targeting, first call search_meta_targeting with search_type='location'. ALWAYS include the 'type' field (city/region/zip/place) on each object — a key with no type is treated as a country code and rejected by Meta. For ~dozens of cities each with a radius, pass one object per city. Default: ['US']
`location_types`	`array` optional	Geo reach mode (a.k.a. location expansion / 'people interested in this location'). List of: 'home' (people who live there), 'recent' (recently there), 'travel_in' (people interested in / traveling to the location). Meta defaults to ['home','recent'] when omitted. To turn ON location expansion, include 'travel_in' (e.g. ['home','recent','travel_in']).
`age_min`	`integer` optional	Minimum age (18-65). Default: 18 default: `18`
`age_max`	`integer` optional	Maximum age (18-65). Default: 65 default: `65`
`genders`	`array` optional	Gender targeting: ['male'], ['female'], or None for all genders
`interests`	`array` optional	List of interest targeting objects from search_meta_targeting. Format: [{'id': '6003139266461', 'name': 'Fitness'}]. Use search_meta_targeting with search_type='interests' to find valid IDs.
`behaviors`	`array` optional	List of behavior targeting objects from search_meta_targeting. Format: [{'id': '6002714895372', 'name': 'Small business owners'}]. Use search_meta_targeting with search_type='behaviors' to find valid IDs.
`job_titles`	`array` optional	List of job title targeting objects for B2B campaigns. Format: [{'id': '123456', 'name': 'Chief Marketing Officer'}]. Use search_meta_targeting with search_type='job_titles' to find valid IDs.
`work_employers`	`array` optional	List of employer targeting objects for B2B campaigns. Format: [{'id': '123456', 'name': 'Google'}]. Use search_meta_targeting with search_type='work_employers' to find valid IDs.
`life_events`	`array` optional	List of life event targeting objects. Format: [{'id': '123456', 'name': 'Recently engaged'}]. Use search_meta_targeting with search_type='life_events' to find valid IDs.
`education_schools`	`array` optional	List of education school targeting objects. Format: [{'id': '123456', 'name': 'Harvard University'}]. Use search_meta_targeting with search_type='education_schools' to find valid IDs.
`education_majors`	`array` optional	List of education major targeting objects. Format: [{'id': '123456', 'name': 'Computer Science'}]. Use search_meta_targeting with search_type='education_majors' to find valid IDs.
`custom_audiences`	`array` optional	List of Custom Audience IDs to include in targeting. These are audiences created in Meta Ads Manager (website visitors, customer lists, etc.)
`excluded_custom_audiences`	`array` optional	List of Custom Audience IDs to exclude from targeting.
`ad_account_id`	`string` optional	Meta Ad Account ID. Required for multi-account users. Get from get_connections_status.
`special_ad_categories`	`array` optional	Special ad categories for housing, credit, employment, or social issues. Options: 'HOUSING', 'CREDIT', 'EMPLOYMENT', 'ISSUES_ELECTIONS_POLITICS'. Leave empty for standard ads.
`lead_form_id`	`string` optional	Lead form ID to attach when objective is OUTCOME_LEADS. Get available forms using list_meta_lead_forms tool. Only used with OUTCOME_LEADS objective.
`optimize_for_reels`	`boolean` optional	Whether to optimize for Reels placement. Set to true for vertical videos (9:16 aspect ratio). default: `false`
`multi_advertiser`	`boolean` optional	Allow ad to appear in multi-advertiser ad format (multiple ads shown together). Set to false to opt out. Default: Meta's default (enabled). Brands that want exclusive placement should set this to false.
`url_tags`	`string` optional	URL parameters (e.g. 'utm_source=meta&utm_medium=cpc&utm_campaign=brand-launch') appended to the landing-page URL on every click. Use for UTM tracking. Leading '?' is stripped automatically.
`ad_set_name`	`string` optional	Custom name for the ad set. When omitted, defaults to '<campaign_name> - Ad Set'. Use this when you want a specific naming convention (e.g. 'Lookalike 1% - US - Nov 2026').
`ad_name`	`string` optional	Custom name for the first ad created with this campaign. When omitted, defaults to '<campaign_name> - Ad'. Use this when you want a specific naming convention for the initial ad.
`display_link`	`string` optional	Optional display URL (also called 'caption') shown in the ad instead of the full landing page URL — e.g. 'brand.com' instead of 'brand.com/summer-sale-landing-page?utm=...'. Must be a domain that reflects the actual landing page domain or Meta rejects the creative at publish. NOT supported on video ads (Meta's video_data has no caption field).
`advantage_audience`	`boolean` optional	Advantage+ Audience (Meta's AI-powered audience expansion). When True, Meta treats hard interests/behaviors/custom_audiences as suggestions rather than strict filters and can deliver beyond them for better performance. When False/None, targeting is strict — Meta only shows ads to users matching the specified filters. Sets targeting.targeting_automation.advantage_audience. NOT compatible with special_ad_categories (HOUSING/CREDIT/EMPLOYMENT/ISSUES_ELECTIONS_POLITICS) — Meta rejects Advantage+ Audience for special-category ads.
`advantage_plus_creative`	`boolean` optional	Master switch for Meta's Advantage+ Creative AI enhancements. Set False to opt OUT of ALL granular enhancements at once (image touchups, auto-crop, text optimizations, enhanced CTA, background generation, etc.). Leave None or True to keep Meta's defaults.
`disabled_creative_features`	`array` optional	List of granular Advantage+ Creative features to opt OUT of individually. Valid field names (from Meta SDK): image_brightness_and_contrast, image_auto_crop, image_background_gen, image_enhancement, image_templates, image_touchups, image_uncrop, text_optimizations, enhance_cta, add_text_overlay, media_liquidity_animated_image, adapt_to_placement, text_generation, description_automation, site_extensions, product_extensions. Unknown names rejected. 'standard_enhancements' is NEVER accepted — Meta deprecated this bundled field in v22 and it triggers error_subcode 3858504 on campaign duplication.
`primary_texts`	`array` optional	List of primary text (body) variations (2-5). USE THIS whenever the user gives you 2 or more primary texts — it creates ONE ad where Meta's asset_feed_spec (Dynamic Creative) tests every body/headline combination, which is what users mean by 'multiple primary texts per creative'. Do NOT instead create separate ads or drop the extras into the singular primary_text field. Supersedes primary_text — provide EITHER primary_text (single) OR primary_texts (list), not both.
`headlines`	`array` optional	List of headline (title) variations (2-5). USE THIS whenever the user gives you 2 or more headlines — it creates ONE ad where Meta's asset_feed_spec (Dynamic Creative) tests every combination. Do NOT instead create separate ads or drop the extras into the singular headline field. Supersedes headline — provide EITHER headline (single) OR headlines (list), not both.
`descriptions`	`array` optional	List of description variations (2-5). Use this whenever the user gives you 2 or more descriptions — Meta's asset_feed_spec (Dynamic Creative) tests the combinations in ONE ad. Supersedes description — provide EITHER description (single) OR descriptions (list), not both.
`publisher_platforms`	`array` optional	Platforms to show ads on. Options: 'facebook', 'instagram', 'audience_network', 'messenger'. Default: automatic (all). To exclude Audience Network/Apps, use ['facebook', 'instagram'].
`facebook_positions`	`array` optional	Facebook placement positions. Options: 'feed', 'right_hand_column', 'marketplace', 'video_feeds', 'story', 'search', 'instream_video', 'facebook_reels'. Only include positions you WANT — omitted positions are excluded.
`instagram_positions`	`array` optional	Instagram placement positions. Options: 'stream' (feed), 'story', 'reels', 'explore', 'explore_home', 'ig_search', 'profile_feed'. Only include positions you WANT — omitted positions are excluded.
`app_id`	`string` optional	Facebook App ID (numeric, registered at developers.facebook.com). Required for OUTCOME_APP_PROMOTION campaigns. NOTE: This is your FB App ID, NOT your iOS bundle ID (com.example.app) or Android package name. Find it in Meta App Dashboard → Settings → Basic.
`app_store_url`	`string` optional	App Store or Play Store listing URL for the promoted app. Required for OUTCOME_APP_PROMOTION campaigns. Examples: 'https://apps.apple.com/us/app/example/id123456789' (iOS), 'https://play.google.com/store/apps/details?id=com.example' (Android). Meta auto-detects platform from the URL.
`app_event_type`	`string` optional	Optional in-app event to optimize for. When omitted, Meta defaults to APP_INSTALLS (install optimization via the ad-set optimization_goal). Provide a specific event to optimize for in-app actions: PURCHASE, LEVEL_ACHIEVED, COMPLETE_REGISTRATION, START_TRIAL, SUBSCRIBE, ADD_TO_CART, ACHIEVEMENT_UNLOCKED, D2_RETENTION, D7_RETENTION, etc. Requires Meta SDK integration in the app to fire the event. Only valid for OUTCOME_APP_PROMOTION.
`deep_link_url_ios`	`string` optional	Optional iOS deep-link URL that opens a specific screen in the app for users who already have it installed (e.g. 'myapp://product/123'). When the user doesn't have the app, the App Store URL opens instead. Requires Universal Links / app_link_spec configured by the app team. Only valid for OUTCOME_APP_PROMOTION.
`deep_link_url_android`	`string` optional	Optional Android deep-link URL (e.g. 'myapp://product/123' or 'intent://product/123#Intent;scheme=myapp;...'). When the user doesn't have the app, the Play Store URL opens instead. Only valid for OUTCOME_APP_PROMOTION.

Field

Type

Description

campaign_name

string required

Campaign name (will be automatically suffixed with timestamp for uniqueness)

objective

string optional

Campaign objective. Options: 'OUTCOME_TRAFFIC' (website clicks), 'OUTCOME_SALES' (conversions), 'OUTCOME_LEADS' (lead forms), 'OUTCOME_AWARENESS' (reach), 'OUTCOME_ENGAGEMENT'. Default: OUTCOME_TRAFFIC default: "OUTCOME_TRAFFIC"

budget_daily

number optional

Daily budget in account currency (minimum $1/day, recommended $5-20/day for testing). Mutually exclusive with budget_lifetime — provide exactly one.

budget_lifetime

number optional

Lifetime budget in account currency (total spend over campaign duration). REQUIRES end_time to be set. Mutually exclusive with budget_daily — provide exactly one.

end_time

string optional

Campaign/ad set end date in ISO format (e.g. '2026-04-30T23:59:59'). REQUIRED when using budget_lifetime. Optional with budget_daily.

video_url

string optional

Public video URL to upload. Video will be uploaded during campaign creation. Supports MP4, MOV formats. Max 4GB, recommended under 1GB. Mutually exclusive with existing_video_id.

existing_video_id

string optional

Existing Meta video ID from your Ad Library. Use this to REUSE videos already uploaded to Meta. Mutually exclusive with video_url.

thumbnail_url

string optional

Optional custom thumbnail image URL. If not provided, Meta will auto-generate thumbnails from video.

facebook_page_id

string optional

Facebook Page ID for the ad. Usually auto-detected from your connected account. Only provide if you have multiple pages and want to use a specific one.

primary_text

string optional

**REQUIRED (this OR `primary_texts`).** Primary ad text (max 2200 characters, recommended 125 or less for optimal display). Ask the user for it before calling this tool. Supports emojis, line breaks (\n), and bullet points (e.g. '🔥 Limited Offer!\n\n✅ Free Shipping\n✅ 30-Day Returns'). This is the main message that appears above the video. ⚠️ If the user supplies MORE THAN ONE primary text variation, do NOT pick one and do NOT use this field — put ALL of them in the `primary_texts` array instead (Meta tests the combinations as Dynamic Creative in a single ad). Use this singular field only for a single body text. Exactly one of `primary_text` or `primary_texts` is required.

headline

string optional

Headline text (max 255 characters, recommended 40). Optional for video ads. Appears below the video on some placements. ⚠️ If the user supplies MORE THAN ONE headline variation, put ALL of them in the `headlines` array field instead of picking one.

landing_page_url

string required

**REQUIRED.** Landing page URL where users will be directed when clicking the ad. Must be HTTPS. Ask the user for it before calling this tool.

call_to_action

string optional

Call-to-action button. Options: 'WATCH_MORE' (default for video), 'LEARN_MORE', 'SHOP_NOW', 'SIGN_UP', 'DOWNLOAD', 'BOOK_TRAVEL', 'CONTACT_US'. Default: WATCH_MORE default: "WATCH_MORE"

description

string optional

Optional description text (max 255 characters, recommended 30). Appears under the headline on some placements. If the user supplies more than one description variation, use the `descriptions` array field instead.

instagram_account_id

string optional

Instagram account ID for Instagram placements. If not provided, ad will run on Facebook only.

pixel_id

string optional

Meta Pixel ID for conversion tracking. Required for OUTCOME_SALES campaigns. Use list_meta_pixels to find available pixels for your ad account.

pixel_event_name

string optional

Conversion event to optimize for when pixel_id is provided. Options: PURCHASE, LEAD, COMPLETE_REGISTRATION, ADD_TO_CART, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, SEARCH, CONTENT_VIEW, OTHER. Use OTHER with custom_conversion_id for custom pixel events. Default: PURCHASE

custom_conversion_id

string optional

Custom conversion ID for optimizing towards a specific custom conversion. When provided, pixel_event_name is ignored — Meta infers the event type from the custom conversion. Get available custom conversions from your Meta Events Manager.

destination_type

string optional

Override the ad set destination type. By default, OUTCOME_LEADS uses ON_AD (Meta lead forms) and OUTCOME_TRAFFIC uses WEBSITE. Set to 'WEBSITE' for OUTCOME_LEADS campaigns that track conversions on your website via Meta Pixel instead of using Meta's built-in lead form. Options: WEBSITE, ON_AD, WEBSITE_AND_ON_AD. Only provide when overriding the default.

campaign_budget_optimization

boolean optional

Enable Advantage Campaign Budget (CBO). When true, the daily budget is set at the campaign level and Meta automatically distributes it across ad sets. When false (default), each ad set manages its own budget. default: false

daily_min_spend_target

number optional

CBO only: minimum daily spend for this ad set in account currency. Meta will try to spend at least this amount on this ad set each day.

daily_spend_cap

number optional

CBO only: maximum daily spend cap for this ad set in account currency. Meta will not spend more than this on this ad set each day.

locations

array optional

Location targeting. Accepts country codes (['US', 'CA']) OR location objects from search_meta_targeting ([{'key': '2421836', 'type': 'city', 'radius': 25, 'distance_unit': 'mile'}]). For city/region targeting, first call search_meta_targeting with search_type='location'. ALWAYS include the 'type' field (city/region/zip/place) on each object — a key with no type is treated as a country code and rejected by Meta. For ~dozens of cities each with a radius, pass one object per city. Default: ['US']

location_types

array optional

Geo reach mode (a.k.a. location expansion / 'people interested in this location'). List of: 'home' (people who live there), 'recent' (recently there), 'travel_in' (people interested in / traveling to the location). Meta defaults to ['home','recent'] when omitted. To turn ON location expansion, include 'travel_in' (e.g. ['home','recent','travel_in']).

age_min

integer optional

Minimum age (18-65). Default: 18 default: 18

age_max

integer optional

Maximum age (18-65). Default: 65 default: 65

genders

array optional

Gender targeting: ['male'], ['female'], or None for all genders

interests

array optional

List of interest targeting objects from search_meta_targeting. Format: [{'id': '6003139266461', 'name': 'Fitness'}]. Use search_meta_targeting with search_type='interests' to find valid IDs.

behaviors

array optional

List of behavior targeting objects from search_meta_targeting. Format: [{'id': '6002714895372', 'name': 'Small business owners'}]. Use search_meta_targeting with search_type='behaviors' to find valid IDs.

job_titles

array optional

List of job title targeting objects for B2B campaigns. Format: [{'id': '123456', 'name': 'Chief Marketing Officer'}]. Use search_meta_targeting with search_type='job_titles' to find valid IDs.

work_employers

array optional

List of employer targeting objects for B2B campaigns. Format: [{'id': '123456', 'name': 'Google'}]. Use search_meta_targeting with search_type='work_employers' to find valid IDs.

life_events

array optional

List of life event targeting objects. Format: [{'id': '123456', 'name': 'Recently engaged'}]. Use search_meta_targeting with search_type='life_events' to find valid IDs.

education_schools

array optional

List of education school targeting objects. Format: [{'id': '123456', 'name': 'Harvard University'}]. Use search_meta_targeting with search_type='education_schools' to find valid IDs.

education_majors

array optional

List of education major targeting objects. Format: [{'id': '123456', 'name': 'Computer Science'}]. Use search_meta_targeting with search_type='education_majors' to find valid IDs.

custom_audiences

array optional

List of Custom Audience IDs to include in targeting. These are audiences created in Meta Ads Manager (website visitors, customer lists, etc.)

excluded_custom_audiences

array optional

List of Custom Audience IDs to exclude from targeting.

ad_account_id

string optional

Meta Ad Account ID. Required for multi-account users. Get from get_connections_status.

special_ad_categories

array optional

Special ad categories for housing, credit, employment, or social issues. Options: 'HOUSING', 'CREDIT', 'EMPLOYMENT', 'ISSUES_ELECTIONS_POLITICS'. Leave empty for standard ads.

lead_form_id

string optional

Lead form ID to attach when objective is OUTCOME_LEADS. Get available forms using list_meta_lead_forms tool. Only used with OUTCOME_LEADS objective.

optimize_for_reels

boolean optional

Whether to optimize for Reels placement. Set to true for vertical videos (9:16 aspect ratio). default: false

multi_advertiser

boolean optional

Allow ad to appear in multi-advertiser ad format (multiple ads shown together). Set to false to opt out. Default: Meta's default (enabled). Brands that want exclusive placement should set this to false.

url_tags

string optional

URL parameters (e.g. 'utm_source=meta&utm_medium=cpc&utm_campaign=brand-launch') appended to the landing-page URL on every click. Use for UTM tracking. Leading '?' is stripped automatically.

ad_set_name

string optional

Custom name for the ad set. When omitted, defaults to '<campaign_name> - Ad Set'. Use this when you want a specific naming convention (e.g. 'Lookalike 1% - US - Nov 2026').

ad_name

string optional

Custom name for the first ad created with this campaign. When omitted, defaults to '<campaign_name> - Ad'. Use this when you want a specific naming convention for the initial ad.

display_link

string optional

Optional display URL (also called 'caption') shown in the ad instead of the full landing page URL — e.g. 'brand.com' instead of 'brand.com/summer-sale-landing-page?utm=...'. Must be a domain that reflects the actual landing page domain or Meta rejects the creative at publish. NOT supported on video ads (Meta's video_data has no caption field).

advantage_audience

boolean optional

Advantage+ Audience (Meta's AI-powered audience expansion). When True, Meta treats hard interests/behaviors/custom_audiences as suggestions rather than strict filters and can deliver beyond them for better performance. When False/None, targeting is strict — Meta only shows ads to users matching the specified filters. Sets targeting.targeting_automation.advantage_audience. NOT compatible with special_ad_categories (HOUSING/CREDIT/EMPLOYMENT/ISSUES_ELECTIONS_POLITICS) — Meta rejects Advantage+ Audience for special-category ads.

advantage_plus_creative

boolean optional

Master switch for Meta's Advantage+ Creative AI enhancements. Set False to opt OUT of ALL granular enhancements at once (image touchups, auto-crop, text optimizations, enhanced CTA, background generation, etc.). Leave None or True to keep Meta's defaults.

disabled_creative_features

array optional

List of granular Advantage+ Creative features to opt OUT of individually. Valid field names (from Meta SDK): image_brightness_and_contrast, image_auto_crop, image_background_gen, image_enhancement, image_templates, image_touchups, image_uncrop, text_optimizations, enhance_cta, add_text_overlay, media_liquidity_animated_image, adapt_to_placement, text_generation, description_automation, site_extensions, product_extensions. Unknown names rejected. 'standard_enhancements' is NEVER accepted — Meta deprecated this bundled field in v22 and it triggers error_subcode 3858504 on campaign duplication.

primary_texts

array optional

List of primary text (body) variations (2-5). **USE THIS whenever the user gives you 2 or more primary texts** — it creates ONE ad where Meta's asset_feed_spec (Dynamic Creative) tests every body/headline combination, which is what users mean by 'multiple primary texts per creative'. Do NOT instead create separate ads or drop the extras into the singular primary_text field. Supersedes primary_text — provide EITHER primary_text (single) OR primary_texts (list), not both.

headlines

array optional

List of headline (title) variations (2-5). **USE THIS whenever the user gives you 2 or more headlines** — it creates ONE ad where Meta's asset_feed_spec (Dynamic Creative) tests every combination. Do NOT instead create separate ads or drop the extras into the singular headline field. Supersedes headline — provide EITHER headline (single) OR headlines (list), not both.

descriptions

array optional

List of description variations (2-5). Use this whenever the user gives you 2 or more descriptions — Meta's asset_feed_spec (Dynamic Creative) tests the combinations in ONE ad. Supersedes description — provide EITHER description (single) OR descriptions (list), not both.

publisher_platforms

array optional

Platforms to show ads on. Options: 'facebook', 'instagram', 'audience_network', 'messenger'. Default: automatic (all). To exclude Audience Network/Apps, use ['facebook', 'instagram'].

facebook_positions

array optional

Facebook placement positions. Options: 'feed', 'right_hand_column', 'marketplace', 'video_feeds', 'story', 'search', 'instream_video', 'facebook_reels'. Only include positions you WANT — omitted positions are excluded.

instagram_positions

array optional

Instagram placement positions. Options: 'stream' (feed), 'story', 'reels', 'explore', 'explore_home', 'ig_search', 'profile_feed'. Only include positions you WANT — omitted positions are excluded.

app_id

string optional

Facebook App ID (numeric, registered at developers.facebook.com). Required for OUTCOME_APP_PROMOTION campaigns. NOTE: This is your FB App ID, NOT your iOS bundle ID (com.example.app) or Android package name. Find it in Meta App Dashboard → Settings → Basic.

app_store_url

string optional

App Store or Play Store listing URL for the promoted app. Required for OUTCOME_APP_PROMOTION campaigns. Examples: 'https://apps.apple.com/us/app/example/id123456789' (iOS), 'https://play.google.com/store/apps/details?id=com.example' (Android). Meta auto-detects platform from the URL.

app_event_type

string optional

Optional in-app event to optimize for. When omitted, Meta defaults to APP_INSTALLS (install optimization via the ad-set optimization_goal). Provide a specific event to optimize for in-app actions: PURCHASE, LEVEL_ACHIEVED, COMPLETE_REGISTRATION, START_TRIAL, SUBSCRIBE, ADD_TO_CART, ACHIEVEMENT_UNLOCKED, D2_RETENTION, D7_RETENTION, etc. Requires Meta SDK integration in the app to fire the event. Only valid for OUTCOME_APP_PROMOTION.

deep_link_url_ios

string optional

Optional iOS deep-link URL that opens a specific screen in the app for users who already have it installed (e.g. 'myapp://product/123'). When the user doesn't have the app, the App Store URL opens instead. Requires Universal Links / app_link_spec configured by the app team. Only valid for OUTCOME_APP_PROMOTION.

deep_link_url_android

string optional

Optional Android deep-link URL (e.g. 'myapp://product/123' or 'intent://product/123#Intent;scheme=myapp;...'). When the user doesn't have the app, the Play Store URL opens instead. Only valid for OUTCOME_APP_PROMOTION.

Example request

{ "arguments": { "campaign_name": "string", "landing_page_url": "https://example.com", "objective": "OUTCOME_TRAFFIC", "budget_daily": 1.0, "budget_lifetime": 1.0, "end_time": "string", "video_url": "string", "existing_video_id": "string" } }

Example responses

200 — Success

{ "success": true, "data": { "text": "(tool-specific textual output for create_meta_video_campaign)", "quota": { "used": 42, "limit": 150, "tier": "plus", "period_end": "2026-05-01" } }, "tool": "create_meta_video_campaign" }

400 — Tool-level error (bad arguments / multi-account selection)

{ "success": false, "error": "You have 25 meta_ads accounts connected. Please specify which account to use by passing the ad_account_id parameter:\n - Acme Holdings (ad_account_id=\"act_123456789\")\n - Acme EU (ad_account_id=\"act_987654321\")", "is_error": true, "tool": "create_meta_video_campaign" }

402 — Quota exhausted

{ "success": false, "error": "\ud83d\udea8 Monthly limit reached (150/150 tool calls on Plus tier).\nUpgrade to Pro at https://adspirer.ai to keep building.", "is_error": true, "tool": "create_meta_video_campaign", "quota": { "used": 150, "limit": 150, "tier": "plus", "period_end": "2026-05-01", "upgrade_url": "https://adspirer.ai" } }

Endpoint

Headers

Description

Request body

Example request

Example responses

200 — Success

400 — Tool-level error (bad arguments / multi-account selection)

402 — Quota exhausted

Try it live