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"

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:

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