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:

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

Or as query parameter:

?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

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

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

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

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

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

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

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

---

Ad Sets

#### List Ad Sets

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

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

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

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

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

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

---

Ads

#### List Ads

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

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

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

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

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

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

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

---

Ad Creatives

#### List Ad Creatives

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

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

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

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

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

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

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

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

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

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

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

Demographic Targeting

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

Gender values: 1 = Male, 2 = Female

Interest Targeting

{
  "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.

{
  "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:

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

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

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
}

Debugging Tokens

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

Recommended: System User Tokens

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

1. Go to Business Settings > Users > System Users

2. Create a new System User with "Admin" role

3. Assign the ad account to the System User

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