Meta Ads

Manage Meta (Facebook) Ads campaigns, ad sets, ads, creatives, and access performance metrics via full read/write API integration.

zachgodsell93@zachgodsell93

Install

openclaw skills install @zachgodsell93/meta-ads

Meta Ads API

Description

Full read/write integration with Meta (Facebook) Ads API for managing campaigns, ad sets, ads, and accessing performance insights/metrics.

Setup

Environment Variables

META_ACCESS_TOKEN - Meta access token (User Access Token or System User Token)
META_AD_ACCOUNT_ID - Your ad account ID (numeric, without act_ prefix)

Required Permissions

ads_read - Read access to ads data
ads_management - Create, edit, and delete ads

Token Types

User Access Token

Short-lived: ~2 hours
Can be extended to 60-90 days
Obtained via OAuth flow or Graph API Explorer

System User Token

No expiration
Recommended for production/automated access
Created in Business Manager

Authentication

All requests require the access token as a query parameter or header:

text

Authorization: Bearer $META_ACCESS_TOKEN
Content-Type: application/json

Or as query parameter:

text

?access_token=$META_ACCESS_TOKEN

API Reference

Base URL: https://graph.facebook.com/v25.0/

Important: Ad account IDs must be prefixed with act_ in API calls (e.g., act_123456789).

Ad Account

Get Ad Account Info

bash

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

Campaigns

List Campaigns

bash

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"

Get Single Campaign

bash

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"

Create Campaign

bash

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": []
  }'

Update Campaign

bash

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"
  }'

Pause Campaign

bash

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"
  }'

Delete Campaign

bash

curl -X DELETE "https://graph.facebook.com/v25.0/{CAMPAIGN_ID}" \
  -H "Authorization: Bearer $META_ACCESS_TOKEN"

Ad Sets

List Ad Sets

bash

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"

Get Single Ad Set

bash

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"

Create Ad Set

bash

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

Update Ad Set

bash

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"
  }'

Pause Ad Set

bash

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"
  }'

Delete Ad Set

bash

curl -X DELETE "https://graph.facebook.com/v25.0/{ADSET_ID}" \
  -H "Authorization: Bearer $META_ACCESS_TOKEN"

List Ads

bash

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"

Get Single Ad

bash

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"

Create Ad

bash

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"
  }'

Create Ad with Inline Creative

bash

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"
  }'

Update Ad

bash

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"
  }'

Pause Ad

bash

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"
  }'

Delete Ad

bash

curl -X DELETE "https://graph.facebook.com/v25.0/{AD_ID}" \
  -H "Authorization: Bearer $META_ACCESS_TOKEN"

Ad Creatives

List Ad Creatives

bash

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"

Create Ad Creative

bash

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"
        }
      }
    }
  }'

Insights (Performance Metrics)

Get Account-Level Insights

bash

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"

Get Campaign Insights

bash

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"

Get Ad Set Insights

bash

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"

Get Ad Insights

bash

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"

Get Insights with Custom Date Range

bash

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"

Get Insights with Breakdowns

bash

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"

Get Insights by Day

bash

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"

Get Insights with Attribution Window

bash

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"

Campaign Objectives

Objective	Description
`OUTCOME_AWARENESS`	Brand awareness and reach
`OUTCOME_ENGAGEMENT`	Post engagement, page likes, event responses
`OUTCOME_TRAFFIC`	Drive traffic to website or app
`OUTCOME_LEADS`	Lead generation
`OUTCOME_APP_PROMOTION`	App installs and engagement
`OUTCOME_SALES`	Conversions and catalog sales

Legacy objectives (still supported):

BRAND_AWARENESS, REACH, LINK_CLICKS, POST_ENGAGEMENT, VIDEO_VIEWS, LEAD_GENERATION, CONVERSIONS, APP_INSTALLS

Targeting Options

Geographic Targeting

json

{
  "geo_locations": {
    "countries": ["US", "CA"],
    "regions": [{"key": "4081"}],
    "cities": [{"key": "2420379", "radius": 25, "distance_unit": "mile"}],
    "zips": [{"key": "US:90210"}]
  }
}

Demographic Targeting

json

{
  "age_min": 25,
  "age_max": 54,
  "genders": [1, 2]
}

Gender values: 1 = Male, 2 = Female

Interest Targeting

json

{
  "flexible_spec": [{
    "interests": [{"id": "6003139266461", "name": "Technology"}]
  }]
}

Budget Types

Type	Description
`daily_budget`	Maximum spend per day (in cents)
`lifetime_budget`	Total budget for campaign/ad set duration (in cents)

Important: Budget values are in the smallest currency unit (cents for USD). Example: 5000 = $50.00

Status Values

Status	Description
`ACTIVE`	Currently running
`PAUSED`	Manually paused
`DELETED`	Soft deleted
`ARCHIVED`	Archived, not running

Available Metrics

Metric	Description
`spend`	Total amount spent
`impressions`	Number of times ads were shown
`clicks`	Number of clicks on ads
`reach`	Number of unique people who saw ads
`frequency`	Average number of times each person saw your ad
`cpc`	Cost per click
`cpm`	Cost per 1,000 impressions
`ctr`	Click-through rate (clicks / impressions)
`cpp`	Cost per 1,000 people reached
`actions`	Total actions (conversions) broken down by type
`action_values`	Value of conversions
`conversions`	Number of conversions
`cost_per_action_type`	Cost per action by type

Attribution Windows

Window	Description
`1d_click`	1-day click attribution
`7d_click`	7-day click attribution (default)
`28d_click`	28-day click attribution
`1d_view`	1-day view-through attribution

Note: As of January 2026, 7-day view (7d_view) and 28-day view (28d_view) attribution windows have been removed. Only 1d_view remains for view-through attribution.

Breakdowns

Breakdown	Description
`age`	Age ranges (18-24, 25-34, etc.)
`gender`	Male, Female, Unknown
`placement`	Where ad was shown (feed, stories, etc.)
`device_platform`	Device type (mobile, desktop)
`platform_position`	Position within platform
`publisher_platform`	Facebook, Instagram, Audience Network
`country`	Country of viewer
`region`	Region/state of viewer

Date Presets

Preset	Description
`today`	Today only
`yesterday`	Yesterday only
`this_month`	Current month
`last_month`	Previous month
`last_7d`	Last 7 days
`last_14d`	Last 14 days
`last_28d`	Last 28 days
`last_30d`	Last 30 days
`last_90d`	Last 90 days

Pagination

The API uses cursor-based pagination. Responses include a paging object with cursors.

json

{
  "data": [...],
  "paging": {
    "cursors": {
      "before": "abc123",
      "after": "xyz789"
    },
    "next": "https://graph.facebook.com/v25.0/..."
  }
}

To get the next page:

bash

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:

Default: 25 records per page
Maximum: 5000 records per page (use limit parameter)

Rate Limits

Rate limits are calculated per ad account using the formula:

text

Call Limit = 60 + (400 × Active Ads) - (0.001 × API Errors)

Minimum: 60 calls per hour
Increases with more active ads
Decreases with API errors

Handling Rate Limits:

Check X-Business-Use-Case-Usage header for current usage
Implement exponential backoff when receiving 429 responses
Start with 1 second delay, double on each retry (max 5 retries)

Token Management

Extending User Access Tokens

Short-lived user tokens (~2 hours) can be exchanged for long-lived tokens (60-90 days):

bash

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:

json

{
  "access_token": "long_lived_token_here",
  "token_type": "bearer",
  "expires_in": 5184000
}

Debugging Tokens

Check token validity and permissions:

bash

curl "https://graph.facebook.com/v25.0/debug_token?input_token={TOKEN_TO_CHECK}&access_token={APP_ID}|{APP_SECRET}"

Recommended: System User Tokens

For production use, create a System User in Business Manager:

Go to Business Settings > Users > System Users
Create a new System User with "Admin" role
Assign the ad account to the System User
Generate a token with ads_read and ads_management permissions

System User tokens do not expire.

Changelog

v1.0.0

Initial release with full read/write access
Ad Account: get info
Campaigns: list, get, create, update, pause, delete
Ad Sets: list, get, create, update, pause, delete with targeting
Ads: list, get, create, update, pause, delete
Ad Creatives: list, create
Insights: account/campaign/adset/ad level with all metrics
Support for breakdowns, date ranges, and attribution windows
Campaign objectives and targeting documentation
Budget types (daily/lifetime) in cents
Pagination documentation
Rate limits and token management

Meta Ads

Install

Meta Ads API

Description

Setup

Environment Variables

Required Permissions

Token Types

Authentication

API Reference

Ad Account

Get Ad Account Info

Campaigns

List Campaigns

Get Single Campaign

Create Campaign

Update Campaign

Pause Campaign

Delete Campaign

Ad Sets

List Ad Sets

Get Single Ad Set

Create Ad Set

Update Ad Set

Pause Ad Set

Delete Ad Set

Ads

List Ads

Get Single Ad

Create Ad

Create Ad with Inline Creative

Update Ad

Pause Ad

Delete Ad

Ad Creatives

List Ad Creatives

Create Ad Creative

Insights (Performance Metrics)

Get Account-Level Insights

Get Campaign Insights

Get Ad Set Insights

Get Ad Insights

Get Insights with Custom Date Range

Get Insights with Breakdowns

Get Insights by Day

Get Insights with Attribution Window

Campaign Objectives

Targeting Options

Geographic Targeting

Demographic Targeting

Interest Targeting

Budget Types

Status Values

Available Metrics

Attribution Windows

Breakdowns

Date Presets

Pagination

Rate Limits

Token Management

Extending User Access Tokens

Debugging Tokens

Recommended: System User Tokens

Changelog

v1.0.0

Related skills