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 requiredPrimary ad text (max 2200 characters, recommended 125 or less for optimal display). 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 requiredList of 2-10 carousel cards. Each card should have: image_url OR image_hash, landing_page_url, headline (max 45 chars), optional description (max 20 chars), optional call_to_action.
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, INITIATE_CHECKOUT, ADD_PAYMENT_INFO, SEARCH, VIEW_CONTENT, 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'. Default: ['US']
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 list_connected_accounts.
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.
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.

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