Meta Ads Analyzer

Meta Ads Analyzer

Use this skill when a user asks an AI agent to inspect Facebook/Instagram Ads campaign performance, active campaigns, spend, CTR, CPC, CPM, leads, or messaging conversations.

The project is read-only. It does not create, edit, pause, or delete campaigns.

Setup

git clone https://github.com/Synero/meta-ads-analyzer.git
cd meta-ads-analyzer

export META_ACCESS_TOKEN="your_meta_access_token"
export META_ACCOUNT_ID="act_123456789"

bash setup.sh

Required Meta permissions usually include:

• ads_read
• ads_management if the user's Meta app/account flow requires it

API version

The default is Graph API v26.0. Pin another version per environment or per call when a workflow needs it:

export META_API_VERSION=v25.0
node meta-ads-cli.js testConnection --apiVersion=v25.0

If Meta deprecates the pinned version, the API returns an error naming it; bump META_API_VERSION or upgrade the CLI instead of retrying.

Commands

./meta-ads.sh test
./meta-ads.sh campaigns
./meta-ads.sh insights
./meta-ads.sh insights --datePreset=last_7d

All commands return JSON.

Intent mapping

Output handling

When summarizing results:

1. State the date preset used.
2. Compare campaigns by objective-relevant metrics.
3. Mention Meta's reporting delay.
4. Do not expose raw access tokens or private account IDs in logs.
5. If the CLI returns status: error, report the error and suggest the smallest fix.

Metrics reference

• spend: amount spent in the selected period.
• impressions: total ad impressions.
• reach: unique accounts reached.
• clicks: click/interactions count from Meta.
• ctr: click-through rate.
• cpc: cost per click.
• cpm: cost per thousand impressions.
• actions: conversion events such as leads or messaging conversations.

Basic heuristics:

• CTR below 1%: review creative, audience, or offer.
• CTR above 2%: usually healthy, depending on vertical.
• Frequency above 3: watch for fatigue if available.
• CPC/CPM must be interpreted relative to objective and market.

Troubleshooting

• META_ACCESS_TOKEN is required: set the token in the environment.
• Permission denied: the app/token probably lacks ads permissions or account access.
• Account not found: check that META_ACCOUNT_ID starts with act_ and belongs to the token's accessible accounts.
• Empty insights: check date preset, campaign delivery, attribution windows, and Meta reporting delays.

Files

• meta-ads.sh: shell wrapper for agents.
• meta-ads-cli.js: zero-dependency Node.js CLI (also importable as a module).
• setup.sh: local setup and syntax checks.
• test/: offline suite against a fake Graph API server; run with npm test.
• .env.example: credential template.