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#

text

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:

text

Authorization: Bearer <ACCESS_TOKEN>

or

text

?access_token=<ACCESS_TOKEN>

---

Permissions Required#

PermissionPurposeads_readRead campaigns, ads, insightsads_managementCreate & update campaigns

---

Core Entities#

• Campaign → Top-level objective
• Ad Set → Budget + targeting
• Ad → Creative (image/video + copy)

---

READ OPERATIONS (Primary)#

1. Get Campaigns#

Endpoint#

text

GET /act_<AD_ACCOUNT_ID>/campaigns

Example#

text

GET /act_<ID>/campaigns?fields=id,name,status,objective

---

2. Get Ad Sets#

text

GET /act_<ID>/adsets?fields=id,name,campaign_id,status,daily_budget

---

3. Get Ads#

text

GET /act_<ID>/ads?fields=id,name,adset_id,status

---

4. Campaign Insights#

text

GET /<CAMPAIGN_ID>/insights?fields=impressions,clicks,spend,ctr,cpc

---

5. Account Insights#

text

GET /act_<ID>/insights?fields=impressions,clicks,spend&date_preset=last_7d

---

6. Time Range Filtering#

text

time_range={'since':'2024-01-01','until':'2024-01-31'}

---

7. Status Filtering#

text

effective_status=['ACTIVE']

---

8. Levels#

text

level=campaign | adset | ad

---

Pagination#

Responses include:

text

paging.next

Agent Rule#

• Follow paging.next until exhausted
• Stop at safe limit (e.g., 10 pages)

---

WRITE OPERATIONS#

9. Create Campaign#

text

POST /act_<ID>/campaigns

Payload:

text

name=My Campaign
objective=CONVERSIONS
status=PAUSED
special_ad_categories=[]

---

10. Create Ad Set#

text

POST /act_<ID>/adsets

Payload:

text

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#

text

POST /act_<ID>/adcreatives

Payload:

text

name=Creative 1
object_story_spec={"page_id":"<PAGE_ID>","link_data":{"message":"Hello","link":"https://example.com"}}

---

12. Create Ad#

text

POST /act_<ID>/ads

Payload:

text

name=Ad 1
adset_id=<ADSET_ID>
creative={"creative_id":"<CREATIVE_ID>"}
status=PAUSED

---

13. Update Campaign Status#

text

POST /<CAMPAIGN_ID>?status=PAUSED

---

INSIGHTS METRICS#

Common fields:

• impressions
• clicks
• spend
• ctr
• cpc
• conversions (if configured)

---

ERROR HANDLING#

CodeMeaning190Invalid/expired token200Permission denied100Invalid 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#

text

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

---