API Reference › Meta Ads › create_meta_carousel_campaign

create_meta_carousel_campaign

Meta Ads Write

User wants to create a Meta (Facebook/Instagram) carousel ad campaign with multiple images

Endpoint

POST https://api.adspirer.ai/api/v1/tools/create_meta_carousel_campaign/execute

Headers

Description

User wants to create a Meta (Facebook/Instagram) carousel ad campaign with multiple images. 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 single image - use `create_meta_image_campaign` instead. DO NOT USE for video - use `create_meta_video_campaign` instead. This tool creates a complete Meta carousel campaign with: 1. Campaign (objective, budget) 2. Ad Set (targeting, placements, schedule) 3. Multiple Image Uploads (one per card) 4. Ad Creative (carousel with child_attachments) 5. Ad (linking creative to ad set) When to use this tool: - "Create a Facebook carousel ad" - "Launch an Instagram carousel campaign" - "Create a multi-product ad" - "Set up an ad with multiple images" 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") - cards: Array of 2-10 cards (see card structure below) Card Structure (each card requires): - image_url OR image_hash: Image source (one required) - landing_page_url: Where users go when clicking this card - headline: Card headline (max 45 chars) - description: Optional card description (max 20 chars) - call_to_action: Optional per-card CTA override Optional Parameters: - facebook_page_id: Auto-detected from connected account - instagram_account_id: Enable Instagram placements - call_to_action: Default CTA for all cards (LEARN_MORE by default) - objective: OUTCOME_TRAFFIC (default), OUTCOME_SALES, OUTCOME_LEADS - locations: Country codes (default: ['US']) - age_min/age_max: Age targeting (18-65) - genders: ['male'], ['female'], or null for all - multi_share_optimized: Let Meta optimize card order (default: true) - pixel_id: Meta Pixel ID for conversion tracking (required for OUTCOME_SALES) - pixel_event_name: Conversion event (PURCHASE, LEAD, etc.) 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.

FieldTypeDescription
campaign_namestring requiredCampaign name (will be automatically suffixed with timestamp for uniqueness)
objectivestring optionalCampaign 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_dailynumber optionalDaily budget in account currency (minimum $1/day, recommended $5-20/day for testing). Mutually exclusive with budget_lifetime — provide exactly one.
budget_lifetimenumber optionalLifetime budget in account currency (total spend over campaign duration). REQUIRES end_time to be set. Mutually exclusive with budget_daily — provide exactly one.
end_timestring optionalCampaign/ad set end date in ISO format (e.g. '2026-04-30T23:59:59'). REQUIRED when using budget_lifetime. Optional with budget_daily.
facebook_page_idstring optionalFacebook 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_textstring required**REQUIRED.** 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 carousel.
cardsarray required**REQUIRED.** List of 2-10 carousel cards. Each card MUST have: image_url OR image_hash, landing_page_url (HTTPS), headline (max 45 chars). Optional per-card: description (max 20 chars), call_to_action. Ask the user for card content before calling this tool.
call_to_actionstring optionalDefault call-to-action button for cards without specific CTA. Options: 'LEARN_MORE', 'SHOP_NOW', 'SIGN_UP', 'DOWNLOAD', 'BOOK_TRAVEL'. Default: LEARN_MORE default: "LEARN_MORE"
instagram_account_idstring optionalInstagram account ID for Instagram placements. If not provided, ad will run on Facebook only.
pixel_idstring optionalMeta Pixel ID for conversion tracking. Required for OUTCOME_SALES campaigns. Use list_meta_pixels to find available pixels for your ad account.
pixel_event_namestring optionalConversion 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_idstring optionalCustom 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_typestring optionalOverride 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_optimizationboolean optionalEnable 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_targetnumber optionalCBO 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_capnumber optionalCBO 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.
locationsarray optionalLocation 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_typesarray optionalGeo 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_mininteger optionalMinimum age (18-65). Default: 18 default: 18
age_maxinteger optionalMaximum age (18-65). Default: 65 default: 65
gendersarray optionalGender targeting: ['male'], ['female'], or None for all genders
interestsarray optionalList 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.
behaviorsarray optionalList 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_titlesarray optionalList 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_employersarray optionalList 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_eventsarray optionalList 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_schoolsarray optionalList 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_majorsarray optionalList 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_audiencesarray optionalList of Custom Audience IDs to include in targeting. These are audiences created in Meta Ads Manager (website visitors, customer lists, etc.)
excluded_custom_audiencesarray optionalList of Custom Audience IDs to exclude from targeting.
ad_account_idstring optionalMeta Ad Account ID. Required for multi-account users. Get from get_connections_status.
special_ad_categoriesarray optionalSpecial ad categories for housing, credit, employment, or social issues. Options: 'HOUSING', 'CREDIT', 'EMPLOYMENT', 'ISSUES_ELECTIONS_POLITICS'. Leave empty for standard ads.
lead_form_idstring optionalLead form ID to attach when objective is OUTCOME_LEADS. Get available forms using list_meta_lead_forms tool. Only used with OUTCOME_LEADS objective.
multi_share_optimizedboolean optionalWhether to let Meta optimize card order based on performance. Default: true (recommended). default: true
multi_advertiserboolean optionalAllow 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_tagsstring optionalURL 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_namestring optionalCustom 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_namestring optionalCustom 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_linkstring optionalOptional 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_audienceboolean optionalAdvantage+ 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_creativeboolean optionalMaster 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_featuresarray optionalList 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_textsarray optionalNOT supported for carousel campaigns — carousel does not use top-level Dynamic-Creative text arrays. For per-card copy variation, set each card's text in cards[]. Passing this will be rejected with a clear error. (Only image/video campaigns accept primary_texts arrays.)
headlinesarray optionalNOT supported for carousel campaigns — use per-card headlines in cards[] instead. Passing this will be rejected.
descriptionsarray optionalNOT supported for carousel campaigns — use per-card descriptions in cards[] instead. Passing this will be rejected.
publisher_platformsarray optionalPlatforms to show ads on. Options: 'facebook', 'instagram', 'audience_network', 'messenger'. Default: automatic (all). To exclude Audience Network/Apps, use ['facebook', 'instagram'].
facebook_positionsarray optionalFacebook 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_positionsarray optionalInstagram placement positions. Options: 'stream' (feed), 'story', 'reels', 'explore', 'explore_home', 'ig_search', 'profile_feed'. Only include positions you WANT — omitted positions are excluded.
app_idstring optionalFacebook 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_urlstring optionalApp 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_typestring optionalOptional 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_iosstring optionalOptional 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_androidstring optionalOptional 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",
    "primary_text": "string",
    "cards": [
      {
        "image_url": "https://example.com/card1.jpg",
        "landing_page_url": "https://example.com/product/1",
        "headline": "Spring Sale",
        "description": "Up to 40% off",
        "call_to_action": "SHOP_NOW"
      },
      {
        "image_url": "https://example.com/card2.jpg",
        "landing_page_url": "https://example.com/product/2",
        "headline": "New Arrivals"
      }
    ],
    "objective": "OUTCOME_TRAFFIC",
    "budget_daily": 1.0,
    "budget_lifetime": 1.0,
    "end_time": "string",
    "facebook_page_id": "string",
    "call_to_action": "LEARN_MORE"
  }
}

Example responses

200 — Success

{
  "success": true,
  "data": {
    "text": "(tool-specific textual output for create_meta_carousel_campaign)",
    "quota": {
      "used": 42,
      "limit": 150,
      "tier": "plus",
      "period_end": "2026-05-01"
    }
  },
  "tool": "create_meta_carousel_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_carousel_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_carousel_campaign",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}

Try it live

Interactive: Swagger UI

Machine-readable: OpenAPI 3.1 spec · llms-full.txt

More tools: Meta Ads · All tools

Adspirer REST API — get an API key at adspirer.ai/keys · adspirer.ai