Create Meta Video Campaign

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:

Campaign (objective, budget)
Ad Set (targeting, placements, schedule)
Video Upload (handles large files with chunked upload)
Ad Creative (video, text, CTA)
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

POST

api

tools

create_meta_video_campaign

execute

Create Meta Video Campaign

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/create_meta_video_campaign/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "budget_daily": 1,
    "budget_lifetime": 1,
    "campaign_name": "string",
    "end_time": "string",
    "existing_video_id": "string",
    "landing_page_url": "https://example.com",
    "objective": "OUTCOME_TRAFFIC",
    "primary_text": "string",
    "video_url": "string"
  }
}
'

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

Authorizations

Authorization

string

header

required

API key from https://adspirer.ai/keys. Prefix sk_live_. Treat as a secret — never commit.

Headers

Idempotency-Key

string<uuid>

Client-generated UUID to make writes idempotent. Strongly recommended for write tools. A repeat call with the same key returns the cached result instead of re-executing. Example: 550e8400-e29b-41d4-a716-446655440000

Body

application/json

All tool arguments are wrapped in an arguments object. The fields accepted inside arguments are listed below — required fields are marked with a red asterisk.

arguments

object

required

Input schema for creating Meta video ad campaigns

Show child attributes

Response

Tool executed successfully. data.text carries the human-readable result (markdown-friendly). data.quota shows your current usage against the plan limit. data.structured appears when the tool emits machine-parseable structured content. data.content appears for tools that return non-text blocks (images, resources).

Returned on HTTP 200. data.text is the primary human-readable output. data.quota is always present for billable calls. data.structured is set only when the tool emits machine-parseable structured content. data.content is set only when the tool emits non-text content blocks.

data

object

required

Show child attributes

success

boolean

required

tool

string

required

Echoed tool_name from the request URL.

Last modified on April 23, 2026

Detect Meta Creative FatigueUser asks about creative fatigue, ad refresh timing, frequency management, declining CTR, when to replace ads, or audience exhaustion on Meta/Facebook/Instagram. This tool analyzes all Meta Ads creatives for fatigue indicators using frequency-CTR correlation analysis and provides a fatigue score (0-100) for each ad. Returns: - Fatigue score (0-100) for each ad based on weighted factors - Severely fatigued ads (score ≥80) - immediate action required - At-risk ads (score 50-79) - plan refresh within 7-14 days - Healthy ads count - Daily spend being wasted on fatigued creatives - Projected monthly waste - Refresh schedule recommendations - Contributing factors for each fatigued ad When to use this tool: - "Are any of my Meta/Facebook/Instagram ads fatigued?" - "When should I refresh my creatives?" - "Why is my CTR declining?" - "Which ads have high frequency?" - "How much am I wasting on fatigued ads?" - "What's my ad refresh schedule?" - "Are my retargeting ads showing too often?" Parameters: - lookback_days: 7, 14, 30 (default), 60, or 90 days - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - frequency_threshold_cold: 2.0-8.0 (default: 4.0) - threshold for cold traffic audiences - frequency_threshold_retargeting: 4.0-10.0 (default: 7.0) - threshold for retargeting audiences - ctr_decline_threshold: 0.10-0.50 (default: 0.20 = 20%) - CTR decline to flag as fatigued - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 2-5 seconds (cached database query with analysis) Data source: meta_ad_creative_metrics table (ad-level daily metrics with frequency, CTR, video completion) Fatigue Score Calculation: The fatigue score (0-100) is calculated using weighted factors: - Frequency (40%): impressions/reach ratio vs threshold - CTR Decline (35%): % drop in CTR vs previous period - Days Running (25%): creative age vs optimal refresh timing Severity Levels: - 🔴 Score ≥80: Severely fatigued - PAUSE immediately and replace - 🟡 Score 50-79: At risk - prepare replacement within 7-14 days - ✅ Score `<`50: Healthy - continue monitoring Best practices: - Cold traffic: Refresh creatives when frequency reaches 3-4x - Retargeting: Can tolerate higher frequency (up to 6-7x) - Create 3-5 variations per ad set for automatic rotation - Monitor weekly for frequency and CTR trends

Create Meta Video Campaign

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/create_meta_video_campaign/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "budget_daily": 1,
    "budget_lifetime": 1,
    "campaign_name": "string",
    "end_time": "string",
    "existing_video_id": "string",
    "landing_page_url": "https://example.com",
    "objective": "OUTCOME_TRAFFIC",
    "primary_text": "string",
    "video_url": "string"
  }
}
'

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