meta-ads

name	meta-ads
description	Manage Meta/Facebook ad campaigns — create, edit, and check performance.
metadata	{"homepage":"https://developers.facebook.com/docs/marketing-apis/"}

Meta Ads API

Setup

• META_ACCESS_TOKEN - Meta access token (User or System User Token)
• META_AD_ACCOUNT_ID - Ad account ID (numeric, without act_ 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}"