# Send Meta Ads to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "meta-ads",
    "name": "Meta Ads",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/zachgodsell93/meta-ads",
    "canonicalUrl": "https://clawhub.ai/zachgodsell93/meta-ads",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/meta-ads",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=meta-ads",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "skill.md"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "meta-ads",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-05T12:53:57.977Z",
      "expiresAt": "2026-05-12T12:53:57.977Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=meta-ads",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=meta-ads",
        "contentDisposition": "attachment; filename=\"meta-ads-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "meta-ads"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/meta-ads"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/meta-ads",
    "downloadUrl": "https://openagent3.xyz/downloads/meta-ads",
    "agentUrl": "https://openagent3.xyz/skills/meta-ads/agent",
    "manifestUrl": "https://openagent3.xyz/skills/meta-ads/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/meta-ads/agent.md"
  }
}
```
## Documentation

### Description

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

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

ObjectiveDescriptionOUTCOME_AWARENESSBrand awareness and reachOUTCOME_ENGAGEMENTPost engagement, page likes, event responsesOUTCOME_TRAFFICDrive traffic to website or appOUTCOME_LEADSLead generationOUTCOME_APP_PROMOTIONApp installs and engagementOUTCOME_SALESConversions and catalog sales

Legacy objectives (still supported):

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

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

TypeDescriptiondaily_budgetMaximum spend per day (in cents)lifetime_budgetTotal 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

StatusDescriptionACTIVECurrently runningPAUSEDManually pausedDELETEDSoft deletedARCHIVEDArchived, not running

### Available Metrics

MetricDescriptionspendTotal amount spentimpressionsNumber of times ads were shownclicksNumber of clicks on adsreachNumber of unique people who saw adsfrequencyAverage number of times each person saw your adcpcCost per clickcpmCost per 1,000 impressionsctrClick-through rate (clicks / impressions)cppCost per 1,000 people reachedactionsTotal actions (conversions) broken down by typeaction_valuesValue of conversionsconversionsNumber of conversionscost_per_action_typeCost per action by type

### Attribution Windows

WindowDescription1d_click1-day click attribution7d_click7-day click attribution (default)28d_click28-day click attribution1d_view1-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

BreakdownDescriptionageAge ranges (18-24, 25-34, etc.)genderMale, Female, UnknownplacementWhere ad was shown (feed, stories, etc.)device_platformDevice type (mobile, desktop)platform_positionPosition within platformpublisher_platformFacebook, Instagram, Audience NetworkcountryCountry of viewerregionRegion/state of viewer

### Date Presets

PresetDescriptiontodayToday onlyyesterdayYesterday onlythis_monthCurrent monthlast_monthPrevious monthlast_7dLast 7 dayslast_14dLast 14 dayslast_28dLast 28 dayslast_30dLast 30 dayslast_90dLast 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)

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

### 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
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: zachgodsell93
- Version: 1.0.0
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-05-05T12:53:57.977Z
- Expires at: 2026-05-12T12:53:57.977Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/meta-ads)
- [Send to Agent page](https://openagent3.xyz/skills/meta-ads/agent)
- [JSON manifest](https://openagent3.xyz/skills/meta-ads/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/meta-ads/agent.md)
- [Download page](https://openagent3.xyz/downloads/meta-ads)