Meta Ads Api
by @otman-ai
Manage Meta ad campaigns by reading, creating, updating campaigns, ad sets, ads, creatives, and retrieving insights via the Marketing API.
clawhub install metaadsπ About This Skill
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_)
Authentication
Method
Use access token in query or header:
Authorization: Bearer
or
?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_/campaigns
Example
GET /act_/campaigns?fields=id,name,status,objective
2. Get Ad Sets
GET /act_/adsets?fields=id,name,campaign_id,status,daily_budget
3. Get Ads
GET /act_/ads?fields=id,name,adset_id,status
4. Campaign Insights
GET //insights?fields=impressions,clicks,spend,ctr,cpc
5. Account Insights
GET /act_/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_/campaigns
Payload:
name=My Campaign
objective=CONVERSIONS
status=PAUSED
special_ad_categories=[]
10. Create Ad Set
POST /act_/adsets
Payload:
name=Ad Set 1
daily_budget=1000
billing_event=IMPRESSIONS
optimization_goal=REACH
campaign_id=
targeting={"geo_locations":{"countries":["MA"]}}
status=PAUSED
11. Create Ad Creative
POST /act_/adcreatives
Payload:
name=Creative 1
object_story_spec={"page_id":"","link_data":{"message":"Hello","link":"https://example.com"}}
12. Create Ad
POST /act_/ads
Payload:
name=Ad 1
adset_id=
creative={"creative_id":""}
status=PAUSED
13. Update Campaign Status
POST /?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
π‘ Examples
GET /act_/campaigns?fields=id,name,status,objective