Meta Ads

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

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

---

### Ads

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

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

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