> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mavera.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Meta Ads (Facebook / Instagram)
> Integrate Mavera with the Meta Marketing API — video ad analysis, creative comparison, audience persona mapping, ad copy focus groups, campaign content pipelines, fatigue detection, Reels analysis, and cross-platform optimization
## 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.
```mermaid theme={"dark"}
flowchart LR
subgraph META["Meta Ads Manager"]
VideoCreatives["Video Creatives"]
AdCopy["Ad Copy"]
AudienceInsights["Audience Insights"]
CampaignMetrics["Campaign Metrics"]
CustomAudiences["Custom Audiences"]
end
subgraph MV["Mavera"]
VideoAnalysis["Video Analysis"]
FocusGroups["Focus Groups"]
Personas
MaveAgent["Mave Agent"]
Generate
BrandVoice["Brand Voice"]
end
subgraph OUT["Outputs"]
CreativeScores["Creative Scores"]
ABResults["A/B Results"]
AudiencePersonas["Audience Personas"]
ContentLibrary["Content Library"]
RefreshRecs["Refresh Recommendations"]
end
VideoCreatives --> VideoAnalysis
AdCopy --> FocusGroups
AudienceInsights --> Personas
CampaignMetrics --> MaveAgent
CampaignMetrics --> BrandVoice
CustomAudiences --> Personas
VideoAnalysis --> CreativeScores
FocusGroups --> ABResults
Personas --> AudiencePersonas
BrandVoice --> ContentLibrary
Generate --> ContentLibrary
MaveAgent --> RefreshRecs
```
**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
Create a [System User](https://business.facebook.com/settings/system-users) 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.
Find your Ad Account ID in [Business Settings → Ad Accounts](https://business.facebook.com/settings/ad-accounts). Format: `act_123456789`.
Get your key from [Mavera dashboard](https://app.mavera.io/settings/api-keys).
```bash theme={"dark"}
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](/integrations/meta-ads/video-analysis) | Video ad creatives | Video Analysis | Emotional, cognitive, behavioral scoring |
| 2 | [Ad Creative Comparison Matrix](/integrations/meta-ads/creative-comparison) | All active creatives | Video Analysis + Mave | Ranked creative matrix |
| 3 | [Audience Insight → Persona Mapping](/integrations/meta-ads/audience-persona-mapping) | Demographics from Insights | Personas | Mapped + custom persona library |
| 4 | [Ad Copy A/B with Focus Groups](/integrations/meta-ads/ad-copy-focus-group) | Ad copy variants | Focus Groups | Headline ratings + click intent |
| 5 | [Campaign-to-Content Pipeline](/integrations/meta-ads/campaign-content-pipeline) | Top campaigns by CTR | Brand Voice + Generate | Blog posts, social content |
| 6 | [Ad Fatigue Detector](/integrations/meta-ads/ad-fatigue-detector) | Frequency + performance | Mave | Fresh angle recommendations |
| 7 | [Instagram Reels Analysis Pipeline](/integrations/meta-ads/reels-analysis) | Reels creatives | Video Analysis + Focus Groups | Hook, recall, purchase intent |
| 8 | [Custom Audience → Focus Group Mirror](/integrations/meta-ads/custom-audience-mirror) | Custom Audience definitions | Personas + Focus Groups | Targeting-mirrored feedback |
| 9 | [Cross-Platform Creative Optimization](/integrations/meta-ads/cross-platform-optimization) | Same creative, 3 placements | Video Analysis + Mave | Placement-specific recommendations |
| 10 | [Lookalike Audience Persona Expansion](/integrations/meta-ads/lookalike-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](https://app.mavera.io/settings/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](https://developers.facebook.com/tools/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
Browse all platform integrations
Official Meta API documentation
Full guide to Mavera Video Analysis
Full reference for synthetic focus groups
Creating and managing personas
AI research agent reference