Meta Ads Analyzer

Description

--- name: meta-ads-analyzer description: "Analyze Facebook/Instagram Ads campaigns via Meta Marketing API. Get campaign data, performance metrics, and insights directly from your ad account." tags: [meta, ads, facebook, instagram, analytics, marketing] related_skills: [] --- # Meta Ads Analyzer Analyze your Facebook/Instagram Ads campaigns in real-time. No CSV exports, no dashboard switching — just ask your agent. ## Install Point your agent to this repo: https://github.com/Synero/meta-ads-openclaw Your agent reads this SKILL.md, sets up credentials, and follows the instructions below. Works with Hermes, OpenClaw, Claude Code, Cursor, or any agent that supports skills/instructions. ## Setup ```bash # Clone git clone https://github.com/Synero/meta-ads-openclaw.git cd meta-ads-openclaw # Configure credentials export META_ACCESS_TOKEN="your_token_here" export META_ACCOUNT_ID="act_123456789" # Test connection bash meta-ads.sh test ``` **Getting your token:** 1. Go to [Graph API Explorer](https://developers.facebook.com/tools/explorer) 2. Select your Meta app 3. Generate token with permissions: `ads_read`, `ads_management` 4. Copy the token ## Commands ```bash bash meta-ads.sh campaigns # List all campaigns bash meta-ads.sh insights # Performance metrics per campaign bash meta-ads.sh test # Verify API connection ``` All commands return JSON. ## How to Use The user asks about their ads in natural language. Extract intent and run the right command. | User says | Command | What to look for | |-----------|---------|-----------------| | "How are my campaigns?" | `insights` | Spend, CTR, top performers | | "Which campaign is best?" | `insights` | Compare CPC, CTR, conversions | | "What's active?" | `campaigns` | Filter by status=ACTIVE | | "Am I spending too much?" | `insights` | Total spend, CPC trends | | "How many leads?" | `insights` | Actions → lead count | ## Metrics Reference | Metric | Field | Healthy range | |--------|-------|---------------| | Spend | `spend` | Depends on budget | | Impressions | `impressions` | — | | Reach | `reach` | — | | Clicks | `clicks` | — | | CTR | `ctr` | >2% good, <1% review creative | | CPC | `cpc` | Lower = better | | CPM | `cpm` | Industry-dependent | | Conversations | `messaging_conversation_started_7d` | — | | Leads | `lead` (in actions) | — | ## Analysis Guidelines ### CTR - 1-2%: Industry average - \>2%: Good performance - <1%: Creative or targeting needs work ### Frequency ``` Frequency = Impressions / Reach ``` - 1-2: Optimal - 2-3: Monitor - \>3: Ad fatigue risk — rotate creatives ### CPC Comparison Compare CPC across campaigns to identify most efficient spend. Lower CPC = better cost efficiency. ### Breakdown Effect Don't pause ad sets based solely on high CPA — the system optimizes across the whole set. Evaluate marginal vs average performance. ## Output Format ```json { "status": "success", "accountId": "act_123456789", "campaigns": [ { "name": "Campaign_Name", "status": "ACTIVE", "daily_budget": "16000", "insights": { "impressions": 226004, "reach": 78024, "clicks": 4282, "ctr": "1.89%", "cpc": "53.17", "spend": "227694", "messaging_conversation_started_7d": 333 } } ] } ``` ## Limitations - Read-only — cannot modify campaigns - 1-2 hour data delay (Meta API) - Token expires ~every 60 days - Meta API rate limits apply ## Troubleshooting **"Invalid token"** — Token expired. Generate a new one at Graph API Explorer. **"Permission denied"** — App missing `ads_read` or `ads_management` permissions. Check app settings. **"Account not found"** — Wrong Account ID. Format: `act_XXXXXXXXX`. ## Project Files - `meta-ads.sh` — Shell wrapper (campaigns, insights, test) - `meta-ads-cli.js` — Node.js CLI that calls Meta Graph API - `setup.sh` — One-time setup script ## API Notes - Meta Graph API v23.0 - No dependencies beyond Node.js 18+ - Free — uses your own Meta app credentials

Security Status