Meta Ads Api

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

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

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

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

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

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

---