Meta Ads API
Setup
META_ACCESS_TOKEN- Meta access token (User or System User Token)META_AD_ACCOUNT_ID- Ad account ID (numeric, withoutact_prefix)
Base URL: https://graph.facebook.com/v25.0/
Important: Ad account IDs must be prefixed with act_ in API calls.
Campaigns
# List
curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/campaigns?fields=id,name,status,objective,daily_budget" \
-H "Authorization: Bearer $META_ACCESS_TOKEN"
# Create
curl -X POST "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/campaigns" \
-H "Authorization: Bearer $META_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"My Campaign","objective":"OUTCOME_TRAFFIC","status":"PAUSED","special_ad_categories":[]}'
# Pause
curl -X POST "https://graph.facebook.com/v25.0/{CAMPAIGN_ID}" \
-H "Authorization: Bearer $META_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"status":"PAUSED"}'
Ad Sets
# Create with targeting
curl -X POST "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/adsets" \
-H "Authorization: Bearer $META_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"My Ad Set","campaign_id":"{CAMPAIGN_ID}","daily_budget":5000,"billing_event":"IMPRESSIONS","optimization_goal":"LINK_CLICKS","targeting":{"geo_locations":{"countries":["US"]},"age_min":18,"age_max":65},"status":"PAUSED"}'
Note: Budget values are in cents (5000 = $50.00).
Insights (Performance Metrics)
# Account-level (last 30 days)
curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/insights?fields=spend,impressions,clicks,reach,cpc,cpm,ctr&date_preset=last_30d" \
-H "Authorization: Bearer $META_ACCESS_TOKEN"
# Campaign-level with breakdowns
curl "https://graph.facebook.com/v25.0/{CAMPAIGN_ID}/insights?fields=spend,impressions,clicks,actions&breakdowns=age,gender&date_preset=last_7d" \
-H "Authorization: Bearer $META_ACCESS_TOKEN"
# Custom date range
curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/insights?fields=spend,impressions,clicks&time_range={\"since\":\"2026-01-01\",\"until\":\"2026-01-31\"}" \
-H "Authorization: Bearer $META_ACCESS_TOKEN"
Campaign Objectives
| Objective | Description |
|---|---|
OUTCOME_AWARENESS | Brand awareness and reach |
OUTCOME_ENGAGEMENT | Post engagement, page likes |
OUTCOME_TRAFFIC | Drive traffic to website/app |
OUTCOME_LEADS | Lead generation |
OUTCOME_APP_PROMOTION | App installs |
OUTCOME_SALES | Conversions and catalog sales |
Key Metrics
| Metric | Description |
|---|---|
spend | Total amount spent |
impressions | Times ads were shown |
clicks | Clicks on ads |
reach | Unique people who saw ads |
cpc / cpm / ctr | Cost per click / per 1K impressions / click-through rate |
actions | Conversions broken down by type |
Attribution Windows
1d_click, 7d_click (default), 28d_click, 1d_view
Date Presets
today, yesterday, last_7d, last_14d, last_30d, last_90d, this_month, last_month
Breakdowns
age, gender, placement, device_platform, publisher_platform, country
Rate Limits
Call Limit = 60 + (400 x Active Ads) - (0.001 x API Errors)
Minimum 60 calls/hour. Check X-Business-Use-Case-Usage header.
Token Management
System User tokens (recommended, no expiration) via Business Manager. User tokens can be extended to 60-90 days via:
curl "https://graph.facebook.com/v25.0/oauth/access_token?grant_type=fb_exchange_token&client_id={APP_ID}&client_secret={APP_SECRET}&fb_exchange_token={SHORT_LIVED_TOKEN}"