Manage Meta ad campaigns by reading, creating, updating campaigns, ad sets, ads, creatives, and retrieving insights via the Marketing API.
# Meta Ads API Skill (Full)
## Overview
This skill enables an agent to read, create, and manage Meta (Facebook/Instagram) ad campaigns via the Marketing API.
---
## Base Configuration
### API Base URL
```
https://graph.facebook.com/v19.0/
```
### Required Inputs
* `access_token`
* `ad_account_id` (format: `act_<ID>`)
---
## Authentication
### Method
Use access token in query or header:
```
Authorization: Bearer <ACCESS_TOKEN>
```
or
```
?access_token=<ACCESS_TOKEN>
```
---
## Permissions Required
| Permission | Purpose |
| -------------- | ----------------------------- |
| ads_read | Read campaigns, ads, insights |
| ads_management | Create & update campaigns |
---
## Core Entities
* Campaign → Top-level objective
* Ad Set → Budget + targeting
* Ad → Creative (image/video + copy)
---
# READ OPERATIONS (Primary)
## 1. Get Campaigns
### Endpoint
```
GET /act_<AD_ACCOUNT_ID>/campaigns
```
### Example
```
GET /act_<ID>/campaigns?fields=id,name,status,objective
```
---
## 2. Get Ad Sets
```
GET /act_<ID>/adsets?fields=id,name,campaign_id,status,daily_budget
```
---
## 3. Get Ads
```
GET /act_<ID>/ads?fields=id,name,adset_id,status
```
---
## 4. Campaign Insights
```
GET /<CAMPAIGN_ID>/insights?fields=impressions,clicks,spend,ctr,cpc
```
---
## 5. Account Insights
```
GET /act_<ID>/insights?fields=impressions,clicks,spend&date_preset=last_7d
```
---
## 6. Time Range Filtering
```
time_range={'since':'2024-01-01','until':'2024-01-31'}
```
---
## 7. Status Filtering
```
effective_status=['ACTIVE']
```
---
## 8. Levels
```
level=campaign | adset | ad
```
---
## Pagination
Responses include:
```
paging.next
```
### Agent Rule
* Follow `paging.next` until exhausted
* Stop at safe limit (e.g., 10 pages)
---
# WRITE OPERATIONS
## 9. Create Campaign
```
POST /act_<ID>/campaigns
```
Payload:
```
name=My Campaign
objective=CONVERSIONS
status=PAUSED
special_ad_categories=[]
```
---
## 10. Create Ad Set
```
POST /act_<ID>/adsets
```
Payload:
```
name=Ad Set 1
daily_budget=1000
billing_event=IMPRESSIONS
optimization_goal=REACH
campaign_id=<CAMPAIGN_ID>
targeting={"geo_locations":{"countries":["MA"]}}
status=PAUSED
```
---
## 11. Create Ad Creative
```
POST /act_<ID>/adcreatives
```
Payload:
```
name=Creative 1
object_story_spec={"page_id":"<PAGE_ID>","link_data":{"message":"Hello","link":"https://example.com"}}
```
---
## 12. Create Ad
```
POST /act_<ID>/ads
```
Payload:
```
name=Ad 1
adset_id=<ADSET_ID>
creative={"creative_id":"<CREATIVE_ID>"}
status=PAUSED
```
---
## 13. Update Campaign Status
```
POST /<CAMPAIGN_ID>?status=PAUSED
```
---
# INSIGHTS METRICS
Common fields:
* impressions
* clicks
* spend
* ctr
* cpc
* conversions (if configured)
---
# ERROR HANDLING
| Code | Meaning |
| ---- | --------------------- |
| 190 | Invalid/expired token |
| 200 | Permission denied |
| 100 | Invalid parameter |
---
# RATE LIMITS
* Respect HTTP 429
* Retry with exponential backoff
* Batch requests when possible
---
# AGENT RULES (IMPORTANT)
## Safety
* Always create campaigns as `PAUSED`
* Never expose access tokens
* Validate all IDs before use
## Efficiency
* Cache campaign lists
* Avoid duplicate API calls
* Use insights endpoints instead of raw data when possible
## Reliability
* Retry failed requests (max 3)
* Log all API responses
* Detect empty responses
---
# ANALYTICS LOGIC (Agent Intelligence)
## Detect Poor Performance
* High spend + low CTR → flag
* High CPC → recommend pause
## Detect Winners
* High CTR + low CPC → scale budget
## Example Rule
```
IF spend > 50 AND ctr < 0.5%
THEN mark campaign as underperforming
```
---
# SAMPLE REQUEST FLOW
1. Fetch campaigns
2. Fetch insights
3. Analyze metrics
4. Decide action
5. Update campaign (pause/scale)
---
# BEST PRACTICES
* Use long-lived tokens
* Prefer system users (Business Manager)
* Monitor token expiration
* Use versioned API (v19.0+)
---
# NOTES
* Insights are delayed (not real-time)
* Conversion tracking requires Pixel or CAPI
* Some features require app review
---
don't have the plugin yet? install it then click "run inline in claude" again.