> ## Documentation Index
> Fetch the complete documentation index at: https://www.adspirer.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Meta Ads Integration | Adspirer
> Manage Facebook and Instagram campaigns with Adspirer's 54 MCP tools: image, video, carousel, and Advantage+ Catalog (dynamic product) ads, creative fatigue, audiences, and performance.
## Prerequisites
* Meta Business Manager account ([create one here](https://business.facebook.com))
* An active Meta ad account with billing information
* Admin access to the ad account you want to manage
* Adspirer account connected via [Claude Code](/ai-clients/claude-code), [Cursor](/ai-clients/cursor), or any [supported AI client](https://www.adspirer.com/integrations)
## Connecting Meta Ads
Once you've set up Adspirer with your AI client, connect Meta:
1. Open your AI assistant (ChatGPT, Claude, Claude Code, etc.)
2. Say: "Connect my Meta Ads account"
3. Enter your email address when prompted
4. Review and accept the Meta Ads disclaimer — you must check the box acknowledging that Adspirer operates independently from Meta's account enforcement systems before proceeding
5. Adspirer opens your browser for OAuth authorization
6. Sign in to Meta Business Manager and select the **Business Manager(s)** you want to grant access to
7. Approve permissions (read campaign data, create ads, manage budgets)
**Business Manager-wide import.** When you grant access to a Business Manager, Adspirer discovers **every ad account inside that BM**, not just the one you happened to click during OAuth. The Manage Accounts modal at [adspirer.ai/connections](https://adspirer.ai/connections) lists all of them so you can pick which ones to activate.
The disclaimer confirms that you authorize Adspirer to read your campaign data and manage ads through Meta's official Marketing API, and that Adspirer is not responsible for any account actions taken by Meta (security reviews, restrictions, or account disabling).
Verify the connection:
```
Check my connected ad platforms
```
You should see every Meta ad account discovered from your Business Manager listed with name, ID, and active status. Activate the ones you want the agent to work with from the Manage Accounts modal.
### Asset handling across ad accounts
When you ask the agent to launch a creative the agent finds in a **different ad account in the same Business Manager**, Adspirer offers to copy that creative into the target account before creating the campaign. This is **opt-in per call** — the agent asks before copying so you stay in control of which ad account holds which assets. Per-account asset discovery (image, video, creative) is scoped to the specific ad account you're targeting so you don't get false "asset not found" errors when the asset lives one BM over.
**Cross-account safety.** If you ask the agent to add an ad to an ad set — or an ad set to a campaign — that actually belongs to a *different* one of your accounts, Adspirer catches the mismatch up front, names both accounts, and points to the right tool to list the correct entity, instead of letting Meta return a misleading "missing creative" error. Deselected (inactive) ad accounts are also write-protected: the agent can't create or change ads in them until you re-activate them from the Manage Accounts modal.
Adspirer has Meta approved **Ads Management Standard Access**. This means Adspirer uses Meta's official Marketing API with verified permissions to read campaign data and manage ads on your behalf.
Meta's account enforcement systems operate independently from Adspirer. Any account actions taken by Meta — including security reviews, restrictions, or account disabling — are governed by [Meta's Community Standards and policies](https://www.facebook.com/policies/ads/), not by Adspirer.
## What You Can Do (54 Tools)
### Performance Analysis
* `get_meta_campaign_performance` — Pull metrics for campaigns, ad sets, or individual ads
* `get_meta_adset_performance` — Middle-layer analysis: spend, CTR, CPA, ROAS broken down by ad set within a campaign — see which audience segments perform best without going to individual ad level
* `analyze_meta_ad_performance` — Deep analysis of ad-level performance with recommendations
* `get_meta_audience_insights` — Audience breakdown by age, gender, and interests
* `analyze_meta_audiences` — See which audience segments perform best
* `analyze_meta_wasted_spend` — Identify campaigns with poor ROAS and recommend cuts
* `detect_meta_creative_fatigue` — Identify ads losing effectiveness over time
* `explain_meta_anomaly` — Diagnose sudden changes in performance (CPA spikes, CTR drops)
* `get_meta_ad_creatives` — View creative details for ads in a campaign
**Which conversions Adspirer counts.** Performance and results reporting count the conversions Meta actually reports — including **Pixel custom events** (e.g. a Calendly booking), **lead-form submissions**, **Messenger conversations**, and **offline conversions** — with a per-event-name breakdown ("5 *invitee\_select\_time* events," not "5 custom conversions"). Lead-gen and sales campaigns are treated as conversion campaigns in wasted-spend, anomaly, and budget analysis, so the agent won't tell you a lead-gen campaign is "optimizing blind." If you recently optimized for a custom Pixel event and saw 0 conversions in older reports, newly collected data now counts it; historical numbers backfill separately.
The Meta performance dashboard also shows a **conversion breakdown** of every action type and highlights the **purchase-class event** that reconciles with the "Results" column in Meta Ads Manager. So when a "Conversions (all actions)" headline looks higher than Ads Manager — because Meta sums add-to-cart, initiate-checkout, purchase, and more — you can see exactly which figure matches, instead of chasing a phantom discrepancy.
### Targeting & Research
* `search_meta_targeting` — Find audiences by interests, demographics, behaviors
* `browse_meta_targeting` — Explore Meta's targeting categories
* `list_meta_custom_audiences` — View existing custom audiences (database lists, lookalikes, website, engagement)
### Location & geo targeting
Geo targeting is set as part of campaign and ad-set creation — you describe it in plain language and Adspirer builds the correct Meta targeting:
* **Cities, regions, ZIP/postal codes, and countries**, including **city + radius** ("everyone within 20 miles of Austin"). Multiple cities, each with its own radius, work in a single ad set.
* **Location reach modes** — control *who* in a location you reach: people who **live** there, were **recently** there, or are **traveling to / interested in** it.
* **Safer edits** — when you change an ad set's locations with `update_meta_ad_set`, the new geo targeting **merges onto the existing targeting** rather than replacing all of it, so a location-only edit doesn't wipe your audiences and placements.
Create a Meta image campaign targeting people within 15 miles of downtown Denver
who live in the area (not just visitors). Budget \$25/day.
### European Union (EU/EEA) targeting — DSA disclosure
The EU **Digital Services Act (DSA)** requires every ad set that reaches an EU/EEA country to declare who the ad is for. When you create or update an ad set that targets the EU/EEA, supply:
* `dsa_beneficiary` — the person or organization the ad benefits (required for EU/EEA-targeted ad sets)
* `dsa_payor` — the entity paying for the ad (optional; defaults to the beneficiary)
These fields are sent **only** when an ad set actually targets the EU/EEA — non-EU ad sets are unaffected (Meta rejects DSA fields on them). Without a beneficiary, Meta blocks EU-targeted ad sets, so Adspirer asks you for one up front instead of letting the launch fail.
### Campaign Creation
* `select_meta_campaign_type` — Choose between Image, Video, or Carousel based on your creative
* `discover_meta_assets` — Check if you have existing creatives in Meta
* `validate_and_prepare_meta_assets` — Verify images/videos meet Meta's requirements (dimensions, file size, aspect ratio)
* `create_meta_image_campaign` — Launch single-image campaigns (supports lifetime budgets, end dates, placement controls)
* `create_meta_video_campaign` — Launch video campaigns (supports lifetime budgets, end dates, placement controls)
* `create_meta_carousel_campaign` — Launch multi-card carousel campaigns (supports lifetime budgets, end dates, placement controls)
* `create_meta_dco_ad` — Create dynamic creative optimization (DCO) ads — supply multiple headlines and body texts and Meta mixes-and-matches them; Adspirer auto-enables dynamic creative on the target ad set for both image and video
* `duplicate_meta_campaign` — Duplicate an existing campaign with optional modifications
### Catalog & commerce ads (Advantage+ Catalog / Dynamic Product Ads)
Connect a product **catalog** you already manage in Meta Commerce Manager (or synced from Shopify, WooCommerce, or another store platform) and Adspirer builds **dynamic product ads (DPA)** — Meta pulls each product's image, name, and price straight from the catalog and renders the ad automatically. This is how e-commerce advertisers run **prospecting** (show relevant products to cold audiences) and **retargeting** (re-show the exact products a visitor viewed or added to cart) at scale without hand-building an ad per SKU.
* `list_meta_catalogs` — List the product catalogs available to your ad account
* `list_meta_products` — Browse the products inside a catalog
* `list_meta_product_sets` — View existing product sets (targetable subsets of a catalog)
* `create_meta_product_set` — Create a product set with filter rules (e.g. "best sellers under \$50")
* `compare_meta_catalog_product_sets` — Compare performance across product sets to find your winners
* `validate_catalog_readiness` — Pre-flight check that tells you whether your catalog + recent pixel data can support **retargeting** (needs view/add-to-cart/purchase events) or only **prospecting** — before you spend
* `create_meta_catalog_campaign` — Launch an Advantage+ Catalog campaign (prospecting or retargeting), created **PAUSED**
* `add_meta_catalog_ad_set` — Add a catalog ad set (audience, budget, retargeting window)
* `add_meta_catalog_ad` — Add a catalog ad (creative format + product set)
* `update_meta_catalog_campaign` — Change catalog-campaign budget, status, or settings
* `update_meta_catalog_ad_set` — Update catalog ad-set targeting, budget, or retargeting window
* `update_meta_catalog_ad` — Update catalog ad creative or product set
* `analyze_meta_catalog_performance` — Product-level performance across the catalog
* `get_meta_product_performance` — Per-product spend, sales, and ROAS — see which SKUs actually sell
* `detect_meta_catalog_waste` — Flag products burning budget with no return
* `diagnose_meta_catalog_funnel` — Walk the catalog funnel (impressions → view → add-to-cart → purchase) to find where it leaks
Adspirer manages the **ads** on a catalog you've already built in Meta Commerce Manager (or synced from your store platform) — it doesn't create or edit the product feed itself. Set the catalog up once in Commerce Manager, then create, target, and optimize the campaigns with your AI assistant. Catalog campaigns are created **PAUSED** so you can review before spending.
### Lead generation
* `list_meta_lead_forms` — View lead forms configured in your ad account
* `get_meta_lead_form_submissions` — Pull lead submissions from a specific form
### Account & pixel management
* `list_meta_instagram_accounts` — View connected Instagram accounts
* `list_meta_pixels` — View Meta Pixels configured in your ad account
### Optimization
* `optimize_meta_budget` — Reallocate budget based on ROAS or CPA performance
* `optimize_meta_placements` — Shift spend to best-performing placements (Feed, Stories, Reels, etc.)
### Ad set & ad management
* `add_meta_ad_set` — Add ad sets to existing campaigns (supports lifetime budgets, end dates, placements, multi-advertiser opt-out)
* `add_meta_ad` — Add ads to existing ad sets
* `update_meta_campaign` — Change budgets, bids, or targeting
* `update_meta_ad_set` — Update ad set budgets, targeting, or schedule
* `update_meta_ad` — Update ad creative or status
* `pause_meta_campaign` — Stop campaigns or ad sets
* `resume_meta_campaign` — Restart paused campaigns
* `list_meta_campaigns` — List all campaigns with status and budget
* `get_meta_campaign_details` — Detailed campaign info
* `list_meta_ad_sets` — List ad sets in a campaign
* `list_meta_ads` — List ads in an ad set
## Campaign Creation Workflow
Meta campaigns follow a 6-step workflow. Skip steps and the campaign will fail validation.
```
1. get_connections_status
↓ (verify you're managing the right Meta account)
2. search_meta_targeting
↓ (find your target audience)
3. select_meta_campaign_type
↓ (image, video, or carousel?)
4. discover_meta_assets
↓ (check existing creatives)
5. validate_and_prepare_meta_assets
↓ (verify asset URLs meet Meta requirements)
6. create_meta_*_campaign
↓ (image/video/carousel — campaign created PAUSED)
```
## Example Prompts
### Analyze Performance
Pull my Meta Ads performance for the last 30 days.
Show spend, conversions, CPA, and ROAS.
Highlight any campaigns with ROAS below 2.0.
### Detect Creative Fatigue
Check my Meta campaigns for creative fatigue.
Find ads that have been running for 14+ days with declining CTR.
Recommend which creatives to refresh.
### Create an Image Campaign
Create a Meta image campaign:
* Product: Organic skincare line for women 25-45
* Target: Women interested in clean beauty, sustainability, wellness
* Budget: \$30/day
* Creative: \[provide Google Drive link to your image]
* Objective: Website conversions (Add to Cart)
Validate the creative first, then build the campaign.
### Optimize Placements
Analyze my Meta ad placements for the last 14 days.
Which placements have the best CPA? (Feed, Stories, Reels, etc.)
Recommend budget shifts to maximize conversions.
### Audience Analysis
Analyze my Meta audiences.
Which age groups and genders convert best?
What interests correlate with higher ROAS?
Show me a breakdown table.
### Launch an Advantage+ Catalog (Dynamic Product Ads) campaign
List my Meta product catalogs and check whether my catalog is ready for retargeting.
If it is, create an Advantage+ Catalog retargeting campaign for my "Best Sellers"
product set at \$40/day, targeting people who viewed or added to cart in the last 14 days.
Leave it paused so I can review before launch.
## Creative Assets: What You Need to Know
Adspirer does NOT generate images or videos. You provide the creative URLs.
### Supported Asset Sources
* Google Drive (public or shared links)
* Dropbox (public links)
* Amazon S3 (public URLs)
* Any publicly accessible image/video URL
### Meta's Creative Requirements
The `validate_and_prepare_meta_assets` tool checks these automatically:
* **Image ads:** 1080x1080px minimum, JPG or PNG, under 30MB, 1:1 or 4:5 aspect ratio
* **Video ads:** 1080x1080px minimum, MP4 or MOV, under 4GB, 1:1 or 4:5 or 9:16 aspect ratio, 1-240 seconds
* **Carousel ads:** 2-10 cards, each 1080x1080px, JPG or PNG
* **Text limits:** Primary text 125 chars (recommended), headline 27 chars, description 30 chars
## Budget Guidelines
* **Minimum:** \$5/day per ad set (Meta's requirement)
* **Recommended:** \$20+/day for meaningful data
* **Testing:** Start with \$30/day split across 2-3 ad sets to find winners
* **Scaling:** Once you find ROAS above 3.0, increase budget 20-30% every 3 days
## Best Use Cases for Meta Ads
* **E-commerce:** Visual products (fashion, home goods, beauty) — and with **Advantage+ Catalog / dynamic product ads**, show the exact SKUs from your feed to the right shopper automatically
* **Demand generation:** Reach cold audiences with interest-based targeting
* **Retargeting:** Re-engage website visitors and cart abandoners — including **catalog retargeting** that re-shows the precise product someone viewed (also see [Google Display Ads](/ad-platforms/google-display-ads) for retargeting across the open web)
* **Video storytelling:** Brand awareness campaigns with Reels or Stories
* **Lead generation:** On-platform forms (though LinkedIn often performs better for B2B)
## Troubleshooting
### "Ad account not connected" error
Re-authenticate your Meta Business Manager:
```
Connect my Meta Ads account
```
Make sure you select the correct ad account during OAuth. If you manage multiple accounts, you may need to reconnect with admin permissions.
### "Asset validation failed" error
Common causes:
* Image/video URL is private (not publicly accessible)
* Wrong dimensions (Meta requires minimum 1080x1080px)
* File too large (30MB for images, 4GB for video)
* Unsupported format (use JPG/PNG for images, MP4/MOV for video)
Run validation separately to diagnose:
```
Validate this Meta creative: [your URL]
```
### "Campaign creation failed" error
Most common reason: skipping workflow steps. Meta campaigns require all 6 steps in order. If you jump straight to `create_meta_image_campaign` without running `validate_and_prepare_meta_assets` first, it will fail.
Adspirer now catches the most common failure causes *before* they reach Meta and explains them in plain language:
* **Missing pixel on a conversion objective** — a conversion-optimized ad set needs a Meta Pixel (or custom conversion). Adspirer flags this up front instead of letting Meta return the cryptic "promoted object fields missing." Pass a pixel, or pick a non-conversion objective. Use `list_meta_pixels` to find yours.
* **Carousel cards** — each card needs an image, a headline, and a landing-page URL (a carousel-level URL covers cards that don't set their own). Adspirer validates every card before submitting and accepts the same `existing_image_hash` its asset discovery returns, so you can build carousels straight from creatives already in your account.
* **Wrong account** — if the campaign, ad set, or ad you referenced lives in a different one of your ad accounts, Adspirer names the right account instead of failing deep inside Meta. See [Asset handling across ad accounts](#asset-handling-across-ad-accounts).
If you're using [agent skills](/agent-skills/overview), the AI enforces the correct workflow automatically.
### Creative fatigue detection not working
The tool needs at least 14 days of data per ad. If your ads are newer, it can't detect fatigue yet. Wait until ads have run for 2+ weeks.
## FAQ
No. Meta treats Facebook and Instagram as placement options within the same campaign. When you create a Meta campaign through Adspirer, you choose placements (Feed, Stories, Reels, etc.) that span both platforms. You can't create Instagram-only campaigns through the API.
No. Adspirer manages campaigns, not creative production. You provide image/video URLs. For AI-generated creatives, use tools like Midjourney, DALL-E, or Runway, then upload to Google Drive/Dropbox and provide the link.
Yes. Create multiple ad sets with different creatives (different image URLs) but the same targeting and budget. After 7 days, use `analyze_meta_ad_performance` to see which creative wins, then pause the losers and scale the winner.
**Meta Ads:** Best for demand generation (reaching people who don't know you exist) and visual products. Interest-based targeting. Lower intent but cheaper clicks.
**[Google Ads](/ad-platforms/google-ads):** Best for demand capture (reaching people actively searching for solutions). Keyword-based targeting. Higher intent but more expensive clicks.
You build the **catalog** once in Meta Commerce Manager — or sync it automatically from Shopify, WooCommerce, or another store platform — and Adspirer manages the **ads** on top of it. Adspirer reads your catalogs and product sets, checks whether your pixel data can support retargeting (`validate_catalog_readiness`), and creates/optimizes Advantage+ Catalog campaigns. It doesn't edit the product feed itself. Once the catalog exists, you can run everything else — prospecting, retargeting, product-set testing, per-SKU performance — from your AI assistant.
Adspirer pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. A typical Meta campaign creation uses 4-6 tool calls. See [full pricing](https://www.adspirer.com/pricing).
## Related Documentation
* [Google Ads Integration](/ad-platforms/google-ads)
* [LinkedIn Ads Integration](/ad-platforms/linkedin-ads)
* [Campaign Creation Workflows](/agent-skills/workflows)
* [Meta Ads + AI Integration](https://www.adspirer.com/integrations/meta-ads)
* [Pricing & Plans](https://www.adspirer.com/pricing)