Manage Meta (Facebook) Ads campaigns, ad sets, ads, creatives, and access performance metrics via full read/write API integration.
Real data. Real impact.
Emerging
Developers
Per week
Open source
Skills give you superpowers. Install in 30 seconds.
Full read/write integration with Meta (Facebook) Ads API for managing campaigns, ad sets, ads, and accessing performance insights/metrics.
META_ACCESS_TOKENMETA_AD_ACCOUNT_IDact_ads_readads_managementUser Access Token
System User Token
All requests require the access token as a query parameter or header:
Authorization: Bearer $META_ACCESS_TOKEN Content-Type: application/json
Or as query parameter:
?access_token=$META_ACCESS_TOKEN
Base URL:
https://graph.facebook.com/v25.0/Important: Ad account IDs must be prefixed with
act_act_123456789curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID?fields=name,account_status,currency,timezone_name,amount_spent" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/campaigns?fields=id,name,status,objective,daily_budget,lifetime_budget,created_time" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
curl "https://graph.facebook.com/v25.0/{CAMPAIGN_ID}?fields=id,name,status,objective,daily_budget,lifetime_budget,created_time,updated_time" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
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": [] }'
curl -X POST "https://graph.facebook.com/v25.0/{CAMPAIGN_ID}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated Campaign Name", "status": "ACTIVE" }'
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" }'
curl -X DELETE "https://graph.facebook.com/v25.0/{CAMPAIGN_ID}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/adsets?fields=id,name,status,campaign_id,daily_budget,lifetime_budget,targeting,optimization_goal" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
curl "https://graph.facebook.com/v25.0/{ADSET_ID}?fields=id,name,status,campaign_id,daily_budget,lifetime_budget,targeting,optimization_goal,bid_amount,billing_event" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
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", "bid_amount": 200, "targeting": { "geo_locations": { "countries": ["US"] }, "age_min": 18, "age_max": 65 }, "status": "PAUSED" }'
Note: Budget values are in cents (e.g., 5000 = $50.00).
curl -X POST "https://graph.facebook.com/v25.0/{ADSET_ID}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated Ad Set Name", "daily_budget": 10000, "status": "ACTIVE" }'
curl -X POST "https://graph.facebook.com/v25.0/{ADSET_ID}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "PAUSED" }'
curl -X DELETE "https://graph.facebook.com/v25.0/{ADSET_ID}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/ads?fields=id,name,status,adset_id,campaign_id,creative,created_time" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
curl "https://graph.facebook.com/v25.0/{AD_ID}?fields=id,name,status,adset_id,campaign_id,creative,tracking_specs,created_time,updated_time" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
curl -X POST "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/ads" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "My Ad", "adset_id": "{ADSET_ID}", "creative": { "creative_id": "{CREATIVE_ID}" }, "status": "PAUSED" }'
curl -X POST "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/ads" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "My Ad", "adset_id": "{ADSET_ID}", "creative": { "object_story_spec": { "page_id": "{PAGE_ID}", "link_data": { "link": "https://example.com", "message": "Check out our website!", "name": "Example Site", "call_to_action": { "type": "LEARN_MORE" } } } }, "status": "PAUSED" }'
curl -X POST "https://graph.facebook.com/v25.0/{AD_ID}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated Ad Name", "status": "ACTIVE" }'
curl -X POST "https://graph.facebook.com/v25.0/{AD_ID}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "PAUSED" }'
curl -X DELETE "https://graph.facebook.com/v25.0/{AD_ID}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/adcreatives?fields=id,name,object_story_spec,thumbnail_url" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
curl -X POST "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/adcreatives" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "My Creative", "object_story_spec": { "page_id": "{PAGE_ID}", "link_data": { "link": "https://example.com", "message": "Ad copy text here", "name": "Headline", "description": "Description text", "call_to_action": { "type": "SHOP_NOW" } } } }'
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"
curl "https://graph.facebook.com/v25.0/{CAMPAIGN_ID}/insights?fields=spend,impressions,clicks,reach,frequency,cpc,cpm,ctr,actions&date_preset=last_7d" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
curl "https://graph.facebook.com/v25.0/{ADSET_ID}/insights?fields=spend,impressions,clicks,reach,cpc,cpm,ctr,actions&date_preset=last_7d" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
curl "https://graph.facebook.com/v25.0/{AD_ID}/insights?fields=spend,impressions,clicks,reach,cpc,cpm,ctr,actions&date_preset=last_7d" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/insights?fields=spend,impressions,clicks,cpc,cpm,ctr&time_range={\"since\":\"2026-01-01\",\"until\":\"2026-01-31\"}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/insights?fields=spend,impressions,clicks,cpc&breakdowns=age,gender&date_preset=last_7d" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/insights?fields=spend,impressions,clicks&time_increment=1&date_preset=last_7d" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
curl "https://graph.facebook.com/v25.0/{CAMPAIGN_ID}/insights?fields=spend,actions,action_values&action_attribution_windows=[\"7d_click\",\"1d_view\"]&date_preset=last_7d" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
| Objective | Description |
|---|---|
| Brand awareness and reach |
| Post engagement, page likes, event responses |
| Drive traffic to website or app |
| Lead generation |
| App installs and engagement |
| Conversions and catalog sales |
Legacy objectives (still supported):
BRAND_AWARENESSREACHLINK_CLICKSPOST_ENGAGEMENTVIDEO_VIEWSLEAD_GENERATIONCONVERSIONSAPP_INSTALLS{ "geo_locations": { "countries": ["US", "CA"], "regions": [{"key": "4081"}], "cities": [{"key": "2420379", "radius": 25, "distance_unit": "mile"}], "zips": [{"key": "US:90210"}] } }
{ "age_min": 25, "age_max": 54, "genders": [1, 2] }
Gender values:
12{ "flexible_spec": [{ "interests": [{"id": "6003139266461", "name": "Technology"}] }] }
| Type | Description |
|---|---|
| Maximum spend per day (in cents) |
| Total budget for campaign/ad set duration (in cents) |
Important: Budget values are in the smallest currency unit (cents for USD). Example:
5000| Status | Description |
|---|---|
| Currently running |
| Manually paused |
| Soft deleted |
| Archived, not running |
| Metric | Description |
|---|---|
| Total amount spent |
| Number of times ads were shown |
| Number of clicks on ads |
| Number of unique people who saw ads |
| Average number of times each person saw your ad |
| Cost per click |
| Cost per 1,000 impressions |
| Click-through rate (clicks / impressions) |
| Cost per 1,000 people reached |
| Total actions (conversions) broken down by type |
| Value of conversions |
| Number of conversions |
| Cost per action by type |
| Window | Description |
|---|---|
| 1-day click attribution |
| 7-day click attribution (default) |
| 28-day click attribution |
| 1-day view-through attribution |
Note: As of January 2026, 7-day view (
7d_view28d_view1d_view| Breakdown | Description |
|---|---|
| Age ranges (18-24, 25-34, etc.) |
| Male, Female, Unknown |
| Where ad was shown (feed, stories, etc.) |
| Device type (mobile, desktop) |
| Position within platform |
| Facebook, Instagram, Audience Network |
| Country of viewer |
| Region/state of viewer |
| Preset | Description |
|---|---|
| Today only |
| Yesterday only |
| Current month |
| Previous month |
| Last 7 days |
| Last 14 days |
| Last 28 days |
| Last 30 days |
| Last 90 days |
The API uses cursor-based pagination. Responses include a
paging{ "data": [...], "paging": { "cursors": { "before": "abc123", "after": "xyz789" }, "next": "https://graph.facebook.com/v25.0/..." } }
To get the next page:
curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/campaigns?fields=id,name&after={AFTER_CURSOR}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN"
Limits:
limitRate limits are calculated per ad account using the formula:
Call Limit = 60 + (400 × Active Ads) - (0.001 × API Errors)
Handling Rate Limits:
X-Business-Use-Case-UsageShort-lived user tokens (~2 hours) can be exchanged for long-lived tokens (60-90 days):
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}"
Response:
{ "access_token": "long_lived_token_here", "token_type": "bearer", "expires_in": 5184000 }
Check token validity and permissions:
curl "https://graph.facebook.com/v25.0/debug_token?input_token={TOKEN_TO_CHECK}&access_token={APP_ID}|{APP_SECRET}"
For production use, create a System User in Business Manager:
ads_readads_managementSystem User tokens do not expire.
No automatic installation available. Please visit the source repository for installation instructions.
View Installation Instructions
1,500+ AI skills, agents & workflows. Install in 30 seconds. Part of the Torly.ai family.
© 2026 Torly.ai. All rights reserved.