Meta Ads Connection

Connects your agent to Meta Ads Manager for Facebook and Instagram advertising data. Pull campaign performance, ad set metrics, creative performance, audience insights, and conversion data. Read-only access.

Authentication

OAuth2 via Meta Business API.

• access_token — Long-lived user or system user token
• ad_account_id — Ad account ID (act_XXXXXXX)

Required permissions: ads_read, ads_management (for read access to all ad data).

Endpoints

Campaigns

• GET /{ad_account_id}/campaigns — List campaigns with status and objective
• GET /{campaign_id}/insights — Get campaign-level metrics (spend, impressions, CPM, ROAS)

Ad Sets

• GET /{campaign_id}/adsets — List ad sets with targeting and budget
• GET /{adset_id}/insights — Get ad set performance metrics

Ads

• GET /{adset_id}/ads — List ads with creative and status
• GET /{ad_id}/insights — Get ad-level performance with creative breakdown

Audiences

• GET /{ad_account_id}/customaudiences — List custom audiences with size
• GET /{audience_id} — Get audience detail

Conversions

• GET /{ad_account_id}/insights — Get conversion data with attribution breakdown

Rules

• Rate limit: follows Meta Marketing API rate limits (percentage-based)
• The agent requests 7-day click and 1-day view attribution by default
• Breakdowns (age, gender, placement) are available per request
• The agent compares performance to prior period and flags significant changes
• Cost metrics normalized to the ad account's currency