Meta Ads (Facebook / Instagram)

Overview

Pull creative assets, audience insights, and campaign performance from Meta Marketing API (Facebook & Instagram) → analyze with Mavera (Video Analysis, Focus Groups, Personas, Mave, Generate, Brand Voice) → get persona-validated creative intelligence for paid media teams.

Meta Marketing API — Base URL: https://graph.facebook.com/v24.0/. Auth: OAuth 2.0 with System User tokens. Rate limits: 9,000 points / 300 seconds (sliding window). Each GET costs 1 point; batch calls cost 1 point per nested request.

Prerequisites

Meta System User token

Create a System User in Business Manager. Generate a token with permissions: ads_read, ads_management, pages_read_engagement, instagram_basic. Use a long-lived token or implement token refresh.

Ad Account ID

Find your Ad Account ID in Business Settings → Ad Accounts. Format: act_123456789.

Mavera API key

Get your key from Mavera dashboard.

Environment variables

export META_ACCESS_TOKEN="EAAxxxxxxx..."
export META_AD_ACCOUNT_ID="act_123456789"
export MAVERA_API_KEY="mvra_live_xxxxx"

Jobs

#	Job	Meta Data	Mavera Surface	Output
1	Ad Creative Video Analysis	Video ad creatives	Video Analysis	Emotional, cognitive, behavioral scoring
2	Ad Creative Comparison Matrix	All active creatives	Video Analysis + Mave	Ranked creative matrix
3	Audience Insight → Persona Mapping	Demographics from Insights	Personas	Mapped + custom persona library
4	Ad Copy A/B with Focus Groups	Ad copy variants	Focus Groups	Headline ratings + click intent
5	Campaign-to-Content Pipeline	Top campaigns by CTR	Brand Voice + Generate	Blog posts, social content
6	Ad Fatigue Detector	Frequency + performance	Mave	Fresh angle recommendations
7	Instagram Reels Analysis Pipeline	Reels creatives	Video Analysis + Focus Groups	Hook, recall, purchase intent
8	Custom Audience → Focus Group Mirror	Custom Audience definitions	Personas + Focus Groups	Targeting-mirrored feedback
9	Cross-Platform Creative Optimization	Same creative, 3 placements	Video Analysis + Mave	Placement-specific recommendations
10	Lookalike Audience Persona Expansion	Lookalike source data	Personas + Mave	Adjacent expansion personas

Rate Limits & Production Notes

Meta API Endpoint	Cost	Strategy
`GET /insights`	1 point per call	Cache daily; batch date ranges
`GET /adcreatives`	1 point per call	Paginate with `after` cursor
`GET /customaudiences`	1 point per call	Cache — audiences change infrequently
`GET /{video-id}` (source)	1 point per call	Download immediately; URLs expire
Budget: 9,000 points / 300s		Monitor via `x-business-use-case-usage` header

The 9,000-point budget is shared across all apps using the same System User. Monitor usage via the x-business-use-case-usage response header. For production pipelines processing 100+ creatives, implement a token-bucket rate limiter and queue video downloads.

Production checklist:

Store META_ACCESS_TOKEN, META_AD_ACCOUNT_ID, and MAVERA_API_KEY in a secrets manager — never commit tokens
System User tokens don’t expire but can be revoked. Implement health checks
Video source URLs are signed and short-lived — download within seconds of fetching
Cache Insights data locally for daily/weekly jobs; use date_preset for rolling windows
Monitor Mavera credits at Dashboard → Usage
Video Analysis is the most credit-intensive operation — batch wisely

Error reference:

Error	Cause	Fix
Meta `190` (OAuthException)	Expired or invalid token	Refresh token or regenerate System User token
Meta `17` (API Too Many Calls)	Rate limit exceeded	Back off; check `x-business-use-case-usage` header
Meta `100` (Invalid parameter)	Wrong field name or filter	Verify against Graph API Explorer
Meta `10` (Permissions error)	Missing permission on token	Add required permission in Business Manager
Mavera `401`	Invalid API key	Rotate key at app.mavera.io/settings
Mavera `413`	Video file too large	Compress video or split into segments before upload
Mavera `422`	Malformed request body	Check required fields (e.g., `asset_id` for video analysis)

What’s Next

All Integrations

Browse all platform integrations

Meta Marketing API

Official Meta API documentation

Video Analysis

Full guide to Mavera Video Analysis

Focus Groups

Full reference for synthetic focus groups

Personas

Creating and managing personas

Mave Agent

AI research agent reference

​Overview

​Prerequisites

​Jobs

​Rate Limits & Production Notes

​What’s Next

All Integrations

Meta Marketing API

Video Analysis

Focus Groups

Personas

Mave Agent

Overview

Prerequisites

Jobs

Rate Limits & Production Notes

What’s Next