{
  "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": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/meta-ads",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=meta-ads",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "skill.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "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."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "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."
        },
        {
          "label": "Upgrade existing",
          "body": "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."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "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."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/meta-ads",
    "agentPageUrl": "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"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "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."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "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."
      },
      {
        "label": "Upgrade existing",
        "body": "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."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Description",
        "body": "Full read/write integration with Meta (Facebook) Ads API for managing campaigns, ad sets, ads, and accessing performance insights/metrics."
      },
      {
        "title": "Environment Variables",
        "body": "META_ACCESS_TOKEN - Meta access token (User Access Token or System User Token)\nMETA_AD_ACCOUNT_ID - Your ad account ID (numeric, without act_ prefix)"
      },
      {
        "title": "Required Permissions",
        "body": "ads_read - Read access to ads data\nads_management - Create, edit, and delete ads"
      },
      {
        "title": "Token Types",
        "body": "User Access Token\n\nShort-lived: ~2 hours\nCan be extended to 60-90 days\nObtained via OAuth flow or Graph API Explorer\n\nSystem User Token\n\nNo expiration\nRecommended for production/automated access\nCreated in Business Manager"
      },
      {
        "title": "Authentication",
        "body": "All requests require the access token as a query parameter or header:\n\nAuthorization: Bearer $META_ACCESS_TOKEN\nContent-Type: application/json\n\nOr as query parameter:\n\n?access_token=$META_ACCESS_TOKEN"
      },
      {
        "title": "API Reference",
        "body": "Base URL: https://graph.facebook.com/v25.0/\n\nImportant: Ad account IDs must be prefixed with act_ in API calls (e.g., act_123456789)."
      },
      {
        "title": "Ad Account",
        "body": "Get Ad Account Info\n\ncurl \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID?fields=name,account_status,currency,timezone_name,amount_spent\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\""
      },
      {
        "title": "Campaigns",
        "body": "List Campaigns\n\ncurl \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/campaigns?fields=id,name,status,objective,daily_budget,lifetime_budget,created_time\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Single Campaign\n\ncurl \"https://graph.facebook.com/v25.0/{CAMPAIGN_ID}?fields=id,name,status,objective,daily_budget,lifetime_budget,created_time,updated_time\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nCreate Campaign\n\ncurl -X POST \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/campaigns\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"My Campaign\",\n    \"objective\": \"OUTCOME_TRAFFIC\",\n    \"status\": \"PAUSED\",\n    \"special_ad_categories\": []\n  }'\n\nUpdate Campaign\n\ncurl -X POST \"https://graph.facebook.com/v25.0/{CAMPAIGN_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Updated Campaign Name\",\n    \"status\": \"ACTIVE\"\n  }'\n\nPause Campaign\n\ncurl -X POST \"https://graph.facebook.com/v25.0/{CAMPAIGN_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"status\": \"PAUSED\"\n  }'\n\nDelete Campaign\n\ncurl -X DELETE \"https://graph.facebook.com/v25.0/{CAMPAIGN_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\""
      },
      {
        "title": "Ad Sets",
        "body": "List Ad Sets\n\ncurl \"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\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Single Ad Set\n\ncurl \"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\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nCreate Ad Set\n\ncurl -X POST \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/adsets\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"My Ad Set\",\n    \"campaign_id\": \"{CAMPAIGN_ID}\",\n    \"daily_budget\": 5000,\n    \"billing_event\": \"IMPRESSIONS\",\n    \"optimization_goal\": \"LINK_CLICKS\",\n    \"bid_amount\": 200,\n    \"targeting\": {\n      \"geo_locations\": {\n        \"countries\": [\"US\"]\n      },\n      \"age_min\": 18,\n      \"age_max\": 65\n    },\n    \"status\": \"PAUSED\"\n  }'\n\nNote: Budget values are in cents (e.g., 5000 = $50.00).\n\nUpdate Ad Set\n\ncurl -X POST \"https://graph.facebook.com/v25.0/{ADSET_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Updated Ad Set Name\",\n    \"daily_budget\": 10000,\n    \"status\": \"ACTIVE\"\n  }'\n\nPause Ad Set\n\ncurl -X POST \"https://graph.facebook.com/v25.0/{ADSET_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"status\": \"PAUSED\"\n  }'\n\nDelete Ad Set\n\ncurl -X DELETE \"https://graph.facebook.com/v25.0/{ADSET_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\""
      },
      {
        "title": "Ads",
        "body": "List Ads\n\ncurl \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/ads?fields=id,name,status,adset_id,campaign_id,creative,created_time\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Single Ad\n\ncurl \"https://graph.facebook.com/v25.0/{AD_ID}?fields=id,name,status,adset_id,campaign_id,creative,tracking_specs,created_time,updated_time\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nCreate Ad\n\ncurl -X POST \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/ads\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"My Ad\",\n    \"adset_id\": \"{ADSET_ID}\",\n    \"creative\": {\n      \"creative_id\": \"{CREATIVE_ID}\"\n    },\n    \"status\": \"PAUSED\"\n  }'\n\nCreate Ad with Inline Creative\n\ncurl -X POST \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/ads\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"My Ad\",\n    \"adset_id\": \"{ADSET_ID}\",\n    \"creative\": {\n      \"object_story_spec\": {\n        \"page_id\": \"{PAGE_ID}\",\n        \"link_data\": {\n          \"link\": \"https://example.com\",\n          \"message\": \"Check out our website!\",\n          \"name\": \"Example Site\",\n          \"call_to_action\": {\n            \"type\": \"LEARN_MORE\"\n          }\n        }\n      }\n    },\n    \"status\": \"PAUSED\"\n  }'\n\nUpdate Ad\n\ncurl -X POST \"https://graph.facebook.com/v25.0/{AD_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Updated Ad Name\",\n    \"status\": \"ACTIVE\"\n  }'\n\nPause Ad\n\ncurl -X POST \"https://graph.facebook.com/v25.0/{AD_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"status\": \"PAUSED\"\n  }'\n\nDelete Ad\n\ncurl -X DELETE \"https://graph.facebook.com/v25.0/{AD_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\""
      },
      {
        "title": "Ad Creatives",
        "body": "List Ad Creatives\n\ncurl \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/adcreatives?fields=id,name,object_story_spec,thumbnail_url\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nCreate Ad Creative\n\ncurl -X POST \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/adcreatives\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"My Creative\",\n    \"object_story_spec\": {\n      \"page_id\": \"{PAGE_ID}\",\n      \"link_data\": {\n        \"link\": \"https://example.com\",\n        \"message\": \"Ad copy text here\",\n        \"name\": \"Headline\",\n        \"description\": \"Description text\",\n        \"call_to_action\": {\n          \"type\": \"SHOP_NOW\"\n        }\n      }\n    }\n  }'"
      },
      {
        "title": "Insights (Performance Metrics)",
        "body": "Get Account-Level Insights\n\ncurl \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/insights?fields=spend,impressions,clicks,reach,cpc,cpm,ctr&date_preset=last_30d\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Campaign Insights\n\ncurl \"https://graph.facebook.com/v25.0/{CAMPAIGN_ID}/insights?fields=spend,impressions,clicks,reach,frequency,cpc,cpm,ctr,actions&date_preset=last_7d\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Ad Set Insights\n\ncurl \"https://graph.facebook.com/v25.0/{ADSET_ID}/insights?fields=spend,impressions,clicks,reach,cpc,cpm,ctr,actions&date_preset=last_7d\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Ad Insights\n\ncurl \"https://graph.facebook.com/v25.0/{AD_ID}/insights?fields=spend,impressions,clicks,reach,cpc,cpm,ctr,actions&date_preset=last_7d\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Insights with Custom Date Range\n\ncurl \"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\\\"}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Insights with Breakdowns\n\ncurl \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/insights?fields=spend,impressions,clicks,cpc&breakdowns=age,gender&date_preset=last_7d\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Insights by Day\n\ncurl \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/insights?fields=spend,impressions,clicks&time_increment=1&date_preset=last_7d\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Insights with Attribution Window\n\ncurl \"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\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\""
      },
      {
        "title": "Campaign Objectives",
        "body": "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\n\nLegacy objectives (still supported):\n\nBRAND_AWARENESS, REACH, LINK_CLICKS, POST_ENGAGEMENT, VIDEO_VIEWS, LEAD_GENERATION, CONVERSIONS, APP_INSTALLS"
      },
      {
        "title": "Geographic Targeting",
        "body": "{\n  \"geo_locations\": {\n    \"countries\": [\"US\", \"CA\"],\n    \"regions\": [{\"key\": \"4081\"}],\n    \"cities\": [{\"key\": \"2420379\", \"radius\": 25, \"distance_unit\": \"mile\"}],\n    \"zips\": [{\"key\": \"US:90210\"}]\n  }\n}"
      },
      {
        "title": "Demographic Targeting",
        "body": "{\n  \"age_min\": 25,\n  \"age_max\": 54,\n  \"genders\": [1, 2]\n}\n\nGender values: 1 = Male, 2 = Female"
      },
      {
        "title": "Interest Targeting",
        "body": "{\n  \"flexible_spec\": [{\n    \"interests\": [{\"id\": \"6003139266461\", \"name\": \"Technology\"}]\n  }]\n}"
      },
      {
        "title": "Budget Types",
        "body": "TypeDescriptiondaily_budgetMaximum spend per day (in cents)lifetime_budgetTotal budget for campaign/ad set duration (in cents)\n\nImportant: Budget values are in the smallest currency unit (cents for USD). Example: 5000 = $50.00"
      },
      {
        "title": "Status Values",
        "body": "StatusDescriptionACTIVECurrently runningPAUSEDManually pausedDELETEDSoft deletedARCHIVEDArchived, not running"
      },
      {
        "title": "Available Metrics",
        "body": "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"
      },
      {
        "title": "Attribution Windows",
        "body": "WindowDescription1d_click1-day click attribution7d_click7-day click attribution (default)28d_click28-day click attribution1d_view1-day view-through attribution\n\nNote: 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."
      },
      {
        "title": "Breakdowns",
        "body": "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"
      },
      {
        "title": "Date Presets",
        "body": "PresetDescriptiontodayToday onlyyesterdayYesterday onlythis_monthCurrent monthlast_monthPrevious monthlast_7dLast 7 dayslast_14dLast 14 dayslast_28dLast 28 dayslast_30dLast 30 dayslast_90dLast 90 days"
      },
      {
        "title": "Pagination",
        "body": "The API uses cursor-based pagination. Responses include a paging object with cursors.\n\n{\n  \"data\": [...],\n  \"paging\": {\n    \"cursors\": {\n      \"before\": \"abc123\",\n      \"after\": \"xyz789\"\n    },\n    \"next\": \"https://graph.facebook.com/v25.0/...\"\n  }\n}\n\nTo get the next page:\n\ncurl \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/campaigns?fields=id,name&after={AFTER_CURSOR}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nLimits:\n\nDefault: 25 records per page\nMaximum: 5000 records per page (use limit parameter)"
      },
      {
        "title": "Rate Limits",
        "body": "Rate limits are calculated per ad account using the formula:\n\nCall Limit = 60 + (400 × Active Ads) - (0.001 × API Errors)\n\nMinimum: 60 calls per hour\nIncreases with more active ads\nDecreases with API errors\n\nHandling Rate Limits:\n\nCheck X-Business-Use-Case-Usage header for current usage\nImplement exponential backoff when receiving 429 responses\nStart with 1 second delay, double on each retry (max 5 retries)"
      },
      {
        "title": "Extending User Access Tokens",
        "body": "Short-lived user tokens (~2 hours) can be exchanged for long-lived tokens (60-90 days):\n\ncurl \"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}\"\n\nResponse:\n\n{\n  \"access_token\": \"long_lived_token_here\",\n  \"token_type\": \"bearer\",\n  \"expires_in\": 5184000\n}"
      },
      {
        "title": "Debugging Tokens",
        "body": "Check token validity and permissions:\n\ncurl \"https://graph.facebook.com/v25.0/debug_token?input_token={TOKEN_TO_CHECK}&access_token={APP_ID}|{APP_SECRET}\""
      },
      {
        "title": "Recommended: System User Tokens",
        "body": "For production use, create a System User in Business Manager:\n\nGo to Business Settings > Users > System Users\nCreate a new System User with \"Admin\" role\nAssign the ad account to the System User\nGenerate a token with ads_read and ads_management permissions\n\nSystem User tokens do not expire."
      },
      {
        "title": "v1.0.0",
        "body": "Initial release with full read/write access\nAd Account: get info\nCampaigns: list, get, create, update, pause, delete\nAd Sets: list, get, create, update, pause, delete with targeting\nAds: list, get, create, update, pause, delete\nAd Creatives: list, create\nInsights: account/campaign/adset/ad level with all metrics\nSupport for breakdowns, date ranges, and attribution windows\nCampaign objectives and targeting documentation\nBudget types (daily/lifetime) in cents\nPagination documentation\nRate limits and token management"
      }
    ],
    "body": "Meta Ads API\nDescription\n\nFull read/write integration with Meta (Facebook) Ads API for managing campaigns, ad sets, ads, and accessing performance insights/metrics.\n\nSetup\nEnvironment Variables\nMETA_ACCESS_TOKEN - Meta access token (User Access Token or System User Token)\nMETA_AD_ACCOUNT_ID - Your ad account ID (numeric, without act_ prefix)\nRequired Permissions\nads_read - Read access to ads data\nads_management - Create, edit, and delete ads\nToken Types\n\nUser Access Token\n\nShort-lived: ~2 hours\nCan be extended to 60-90 days\nObtained via OAuth flow or Graph API Explorer\n\nSystem User Token\n\nNo expiration\nRecommended for production/automated access\nCreated in Business Manager\nAuthentication\n\nAll requests require the access token as a query parameter or header:\n\nAuthorization: Bearer $META_ACCESS_TOKEN\nContent-Type: application/json\n\n\nOr as query parameter:\n\n?access_token=$META_ACCESS_TOKEN\n\nAPI Reference\n\nBase URL: https://graph.facebook.com/v25.0/\n\nImportant: Ad account IDs must be prefixed with act_ in API calls (e.g., act_123456789).\n\nAd Account\nGet Ad Account Info\ncurl \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID?fields=name,account_status,currency,timezone_name,amount_spent\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nCampaigns\nList Campaigns\ncurl \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/campaigns?fields=id,name,status,objective,daily_budget,lifetime_budget,created_time\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Single Campaign\ncurl \"https://graph.facebook.com/v25.0/{CAMPAIGN_ID}?fields=id,name,status,objective,daily_budget,lifetime_budget,created_time,updated_time\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nCreate Campaign\ncurl -X POST \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/campaigns\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"My Campaign\",\n    \"objective\": \"OUTCOME_TRAFFIC\",\n    \"status\": \"PAUSED\",\n    \"special_ad_categories\": []\n  }'\n\nUpdate Campaign\ncurl -X POST \"https://graph.facebook.com/v25.0/{CAMPAIGN_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Updated Campaign Name\",\n    \"status\": \"ACTIVE\"\n  }'\n\nPause Campaign\ncurl -X POST \"https://graph.facebook.com/v25.0/{CAMPAIGN_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"status\": \"PAUSED\"\n  }'\n\nDelete Campaign\ncurl -X DELETE \"https://graph.facebook.com/v25.0/{CAMPAIGN_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nAd Sets\nList Ad Sets\ncurl \"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\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Single Ad Set\ncurl \"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\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nCreate Ad Set\ncurl -X POST \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/adsets\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"My Ad Set\",\n    \"campaign_id\": \"{CAMPAIGN_ID}\",\n    \"daily_budget\": 5000,\n    \"billing_event\": \"IMPRESSIONS\",\n    \"optimization_goal\": \"LINK_CLICKS\",\n    \"bid_amount\": 200,\n    \"targeting\": {\n      \"geo_locations\": {\n        \"countries\": [\"US\"]\n      },\n      \"age_min\": 18,\n      \"age_max\": 65\n    },\n    \"status\": \"PAUSED\"\n  }'\n\n\nNote: Budget values are in cents (e.g., 5000 = $50.00).\n\nUpdate Ad Set\ncurl -X POST \"https://graph.facebook.com/v25.0/{ADSET_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Updated Ad Set Name\",\n    \"daily_budget\": 10000,\n    \"status\": \"ACTIVE\"\n  }'\n\nPause Ad Set\ncurl -X POST \"https://graph.facebook.com/v25.0/{ADSET_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"status\": \"PAUSED\"\n  }'\n\nDelete Ad Set\ncurl -X DELETE \"https://graph.facebook.com/v25.0/{ADSET_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nAds\nList Ads\ncurl \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/ads?fields=id,name,status,adset_id,campaign_id,creative,created_time\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Single Ad\ncurl \"https://graph.facebook.com/v25.0/{AD_ID}?fields=id,name,status,adset_id,campaign_id,creative,tracking_specs,created_time,updated_time\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nCreate Ad\ncurl -X POST \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/ads\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"My Ad\",\n    \"adset_id\": \"{ADSET_ID}\",\n    \"creative\": {\n      \"creative_id\": \"{CREATIVE_ID}\"\n    },\n    \"status\": \"PAUSED\"\n  }'\n\nCreate Ad with Inline Creative\ncurl -X POST \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/ads\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"My Ad\",\n    \"adset_id\": \"{ADSET_ID}\",\n    \"creative\": {\n      \"object_story_spec\": {\n        \"page_id\": \"{PAGE_ID}\",\n        \"link_data\": {\n          \"link\": \"https://example.com\",\n          \"message\": \"Check out our website!\",\n          \"name\": \"Example Site\",\n          \"call_to_action\": {\n            \"type\": \"LEARN_MORE\"\n          }\n        }\n      }\n    },\n    \"status\": \"PAUSED\"\n  }'\n\nUpdate Ad\ncurl -X POST \"https://graph.facebook.com/v25.0/{AD_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Updated Ad Name\",\n    \"status\": \"ACTIVE\"\n  }'\n\nPause Ad\ncurl -X POST \"https://graph.facebook.com/v25.0/{AD_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"status\": \"PAUSED\"\n  }'\n\nDelete Ad\ncurl -X DELETE \"https://graph.facebook.com/v25.0/{AD_ID}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nAd Creatives\nList Ad Creatives\ncurl \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/adcreatives?fields=id,name,object_story_spec,thumbnail_url\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nCreate Ad Creative\ncurl -X POST \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/adcreatives\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"My Creative\",\n    \"object_story_spec\": {\n      \"page_id\": \"{PAGE_ID}\",\n      \"link_data\": {\n        \"link\": \"https://example.com\",\n        \"message\": \"Ad copy text here\",\n        \"name\": \"Headline\",\n        \"description\": \"Description text\",\n        \"call_to_action\": {\n          \"type\": \"SHOP_NOW\"\n        }\n      }\n    }\n  }'\n\nInsights (Performance Metrics)\nGet Account-Level Insights\ncurl \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/insights?fields=spend,impressions,clicks,reach,cpc,cpm,ctr&date_preset=last_30d\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Campaign Insights\ncurl \"https://graph.facebook.com/v25.0/{CAMPAIGN_ID}/insights?fields=spend,impressions,clicks,reach,frequency,cpc,cpm,ctr,actions&date_preset=last_7d\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Ad Set Insights\ncurl \"https://graph.facebook.com/v25.0/{ADSET_ID}/insights?fields=spend,impressions,clicks,reach,cpc,cpm,ctr,actions&date_preset=last_7d\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Ad Insights\ncurl \"https://graph.facebook.com/v25.0/{AD_ID}/insights?fields=spend,impressions,clicks,reach,cpc,cpm,ctr,actions&date_preset=last_7d\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Insights with Custom Date Range\ncurl \"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\\\"}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Insights with Breakdowns\ncurl \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/insights?fields=spend,impressions,clicks,cpc&breakdowns=age,gender&date_preset=last_7d\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Insights by Day\ncurl \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/insights?fields=spend,impressions,clicks&time_increment=1&date_preset=last_7d\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nGet Insights with Attribution Window\ncurl \"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\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\nCampaign Objectives\nObjective\tDescription\nOUTCOME_AWARENESS\tBrand awareness and reach\nOUTCOME_ENGAGEMENT\tPost engagement, page likes, event responses\nOUTCOME_TRAFFIC\tDrive traffic to website or app\nOUTCOME_LEADS\tLead generation\nOUTCOME_APP_PROMOTION\tApp installs and engagement\nOUTCOME_SALES\tConversions and catalog sales\n\nLegacy objectives (still supported):\n\nBRAND_AWARENESS, REACH, LINK_CLICKS, POST_ENGAGEMENT, VIDEO_VIEWS, LEAD_GENERATION, CONVERSIONS, APP_INSTALLS\nTargeting Options\nGeographic Targeting\n{\n  \"geo_locations\": {\n    \"countries\": [\"US\", \"CA\"],\n    \"regions\": [{\"key\": \"4081\"}],\n    \"cities\": [{\"key\": \"2420379\", \"radius\": 25, \"distance_unit\": \"mile\"}],\n    \"zips\": [{\"key\": \"US:90210\"}]\n  }\n}\n\nDemographic Targeting\n{\n  \"age_min\": 25,\n  \"age_max\": 54,\n  \"genders\": [1, 2]\n}\n\n\nGender values: 1 = Male, 2 = Female\n\nInterest Targeting\n{\n  \"flexible_spec\": [{\n    \"interests\": [{\"id\": \"6003139266461\", \"name\": \"Technology\"}]\n  }]\n}\n\nBudget Types\nType\tDescription\ndaily_budget\tMaximum spend per day (in cents)\nlifetime_budget\tTotal budget for campaign/ad set duration (in cents)\n\nImportant: Budget values are in the smallest currency unit (cents for USD). Example: 5000 = $50.00\n\nStatus Values\nStatus\tDescription\nACTIVE\tCurrently running\nPAUSED\tManually paused\nDELETED\tSoft deleted\nARCHIVED\tArchived, not running\nAvailable Metrics\nMetric\tDescription\nspend\tTotal amount spent\nimpressions\tNumber of times ads were shown\nclicks\tNumber of clicks on ads\nreach\tNumber of unique people who saw ads\nfrequency\tAverage number of times each person saw your ad\ncpc\tCost per click\ncpm\tCost per 1,000 impressions\nctr\tClick-through rate (clicks / impressions)\ncpp\tCost per 1,000 people reached\nactions\tTotal actions (conversions) broken down by type\naction_values\tValue of conversions\nconversions\tNumber of conversions\ncost_per_action_type\tCost per action by type\nAttribution Windows\nWindow\tDescription\n1d_click\t1-day click attribution\n7d_click\t7-day click attribution (default)\n28d_click\t28-day click attribution\n1d_view\t1-day view-through attribution\n\nNote: 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.\n\nBreakdowns\nBreakdown\tDescription\nage\tAge ranges (18-24, 25-34, etc.)\ngender\tMale, Female, Unknown\nplacement\tWhere ad was shown (feed, stories, etc.)\ndevice_platform\tDevice type (mobile, desktop)\nplatform_position\tPosition within platform\npublisher_platform\tFacebook, Instagram, Audience Network\ncountry\tCountry of viewer\nregion\tRegion/state of viewer\nDate Presets\nPreset\tDescription\ntoday\tToday only\nyesterday\tYesterday only\nthis_month\tCurrent month\nlast_month\tPrevious month\nlast_7d\tLast 7 days\nlast_14d\tLast 14 days\nlast_28d\tLast 28 days\nlast_30d\tLast 30 days\nlast_90d\tLast 90 days\nPagination\n\nThe API uses cursor-based pagination. Responses include a paging object with cursors.\n\n{\n  \"data\": [...],\n  \"paging\": {\n    \"cursors\": {\n      \"before\": \"abc123\",\n      \"after\": \"xyz789\"\n    },\n    \"next\": \"https://graph.facebook.com/v25.0/...\"\n  }\n}\n\n\nTo get the next page:\n\ncurl \"https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/campaigns?fields=id,name&after={AFTER_CURSOR}\" \\\n  -H \"Authorization: Bearer $META_ACCESS_TOKEN\"\n\n\nLimits:\n\nDefault: 25 records per page\nMaximum: 5000 records per page (use limit parameter)\nRate Limits\n\nRate limits are calculated per ad account using the formula:\n\nCall Limit = 60 + (400 × Active Ads) - (0.001 × API Errors)\n\nMinimum: 60 calls per hour\nIncreases with more active ads\nDecreases with API errors\n\nHandling Rate Limits:\n\nCheck X-Business-Use-Case-Usage header for current usage\nImplement exponential backoff when receiving 429 responses\nStart with 1 second delay, double on each retry (max 5 retries)\nToken Management\nExtending User Access Tokens\n\nShort-lived user tokens (~2 hours) can be exchanged for long-lived tokens (60-90 days):\n\ncurl \"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}\"\n\n\nResponse:\n\n{\n  \"access_token\": \"long_lived_token_here\",\n  \"token_type\": \"bearer\",\n  \"expires_in\": 5184000\n}\n\nDebugging Tokens\n\nCheck token validity and permissions:\n\ncurl \"https://graph.facebook.com/v25.0/debug_token?input_token={TOKEN_TO_CHECK}&access_token={APP_ID}|{APP_SECRET}\"\n\nRecommended: System User Tokens\n\nFor production use, create a System User in Business Manager:\n\nGo to Business Settings > Users > System Users\nCreate a new System User with \"Admin\" role\nAssign the ad account to the System User\nGenerate a token with ads_read and ads_management permissions\n\nSystem User tokens do not expire.\n\nChangelog\nv1.0.0\nInitial release with full read/write access\nAd Account: get info\nCampaigns: list, get, create, update, pause, delete\nAd Sets: list, get, create, update, pause, delete with targeting\nAds: list, get, create, update, pause, delete\nAd Creatives: list, create\nInsights: account/campaign/adset/ad level with all metrics\nSupport for breakdowns, date ranges, and attribution windows\nCampaign objectives and targeting documentation\nBudget types (daily/lifetime) in cents\nPagination documentation\nRate limits and token management"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/zachgodsell93/meta-ads",
    "publisherUrl": "https://clawhub.ai/zachgodsell93/meta-ads",
    "owner": "zachgodsell93",
    "version": "1.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "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"
  }
}