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 <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