Add Meta Ad

User wants to add another ad/creative variation to an EXISTING ad set.

DO NOT USE to create a new campaign. For new campaigns:

Video campaign - create_meta_video_campaign
Image campaign - create_meta_image_campaign
Carousel campaign - create_meta_carousel_campaign

Common scenarios:

A/B test ad copy: Different headlines, primary text, or CTAs for the same audience
A/B test creatives: Different images or videos for the same audience
Format testing within one audience: Image vs video ad in the same ad set
Dynamic Creative (DCO): Multiple images + text variations in one ad — Meta auto-optimizes

KEY DISTINCTION — add_meta_ad vs add_meta_ad_set:

Same audience, different creative/copy - use THIS tool (add_meta_ad)
Different audience/targeting - use add_meta_ad_set instead (creates a new ad set)

Ads in the same ad set SHARE: targeting, budget, schedule, pixel tracking. Each ad has its OWN: creative (image/video/carousel), headline, primary text, CTA, landing page.

IMPORTANT: You need an ad_set_id from a previously created ad set. Use list_meta_ad_sets first if you don’t have the ad_set_id.

Supports all 3 ad types + Dynamic Creative:

image: Different image + copy variation
video: Different video + copy variation
carousel: Different card set + copy variation
Dynamic Creative (DCO): Pass image_urls (2-10 images), headlines (up to 5), primary_texts (up to 5), descriptions (up to 5). Meta tests ALL combinations and optimizes delivery automatically.

Dynamic Creative Optimization (DCO) workflow:

Create ad set with is_dynamic_creative=true via add_meta_ad_set
Call this tool with image_urls (list of 2-10 image URLs), plus optional headlines, primary_texts, descriptions arrays
Meta will test all image × headline × text combinations and optimize
DCO ad sets support only 1 ad — if the ad set already has is_dynamic_creative enabled, this tool auto-detects it Note: Cannot mix image_urls (DCO) with image_url (single image) or placement-specific images.

Standard workflow:

Get ad_set_id from prior campaign creation or list_meta_ad_sets
Write variant ad copy (different headline/primary_text/image)
Call this tool with ad_set_id + new creative + copy

POST

api

tools

add_meta_ad

execute

Add Meta Ad

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/add_meta_ad/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "ad_set_id": "string",
    "ad_type": "string",
    "asset_bundle_id": "string",
    "existing_image_hash": "string",
    "image_url": "string",
    "landing_page_url": "https://example.com",
    "primary_text": "string",
    "right_column_image_url": "string",
    "story_image_url": "string",
    "video_url": "string"
  }
}
'

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

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 adding a new ad to an existing ad set

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

Add Meta Ad SetUser wants to add a new ad set to an EXISTING campaign. Common scenarios: - Audience testing: Same ad format, different targeting/interests per ad set (e.g., "4 ad sets with different interests") - Multi-format: Different ad types (image + video + carousel) under one campaign - Budget split: Same creative, different budgets per audience segment - Scaling: Adding new audiences/markets to an existing campaign - Geographic split: Same ad, different locations per ad set - Dynamic Creative (DCO): Set is_dynamic_creative=true, then use add_meta_ad with image_urls/headlines/primary_texts CRITICAL: Each `create_meta_*_campaign` creates a NEW campaign. To add more ad sets to the SAME campaign, you MUST use this tool. NEVER call create_meta_*_campaign again for the same campaign. IMPORTANT: You need a campaign_id from a previously created campaign. Use `get_meta_campaign_details` first if you don't have the campaign_id. Supports all 3 ad types: - `image`: Provide image_url, existing_image_hash, or asset_bundle_id - `video`: Provide video_url or existing_video_id - `carousel`: Provide cards array (2-10 cards) Dynamic Creative Optimization (DCO): - Set `is_dynamic_creative=true` when creating the ad set - Then use `add_meta_ad` with `image_urls` (2-10), `headlines` (up to 5), `primary_texts` (up to 5) to add a DCO ad - Meta automatically tests all asset combinations and optimizes delivery - DCO ad sets support only 1 ad — one ad with multiple asset variations Each ad set has INDEPENDENT: targeting, budget, schedule, pixel/conversion tracking. Shared from campaign: objective, campaign name. **CBO (Advantage Campaign Budget) campaigns:** If the campaign uses CBO (campaign_budget_optimization=true when created), you MUST: - Set `campaign_budget_optimization: true` on this tool call - Do NOT set `budget_daily` (budget is managed at campaign level) - Optionally set `daily_min_spend_target` and `daily_spend_cap` to control spend distribution If the campaign does NOT use CBO, `budget_daily` is required as usual. Workflow: 1. Create initial campaign with `create_meta_*_campaign` - get campaign_id 2. Call this tool with the campaign_id for each additional ad set 3. Use `add_meta_ad` to add more ad copies/creatives within any ad set

Add Meta Ad

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/add_meta_ad/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "ad_set_id": "string",
    "ad_type": "string",
    "asset_bundle_id": "string",
    "existing_image_hash": "string",
    "image_url": "string",
    "landing_page_url": "https://example.com",
    "primary_text": "string",
    "right_column_image_url": "string",
    "story_image_url": "string",
    "video_url": "string"
  }
}
'

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