meta_get_ad_performance
Per-ad metrics for a period: spend, View Content, Add to Cart, VC→ATC rate, cost per ATC, leads (form / website) and cost per lead, conversations, plus purchase ROAS/CPA/AOV when that pixel fired, CPC (link), landing page views (cost, rate per link click), click→lead rate, checkouts and registrations with their costs, hook/hold, video retention (25/50/75/95/100% view rates over 3-second plays, average watch time — null on statics and on days synced before retention was stored), and the persona / angle / concept parsed from the ad name.
read meta_get_ad_performance
Per-ad metrics for a period: spend, View Content, Add to Cart, VC→ATC rate, cost per ATC, leads (form / website) and cost per lead, conversations, plus purchase ROAS/CPA/AOV when that pixel fired, CPC (link), landing page views (cost, rate per link click), click→lead rate, checkouts and registrations with their costs, hook/hold, video retention (25/50/75/95/100% view rates over 3-second plays, average watch time — null on statics and on days synced before retention was stored), and the persona / angle / concept parsed from the ad name. status is Meta's effective status — ACTIVE means delivering.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
period | 7d | 14d | 30d | this_week | last_week | No | Reporting window. 7d/14d/30d are the last N complete days, ending yesterday (as in Ads Manager); weeks are Monday-based, this_week runs to today. UTC. |
since | string | No | Custom window start, YYYY-MM-DD, UTC. Overrides period. The result's coverage says what the warehouse holds. |
until | string | No | Custom window end, YYYY-MM-DD, inclusive. Default today. |
sort | spend | roas | cpa | purchases | hook | atc | leads | costPerLead | conversations | No | |
limit | integer | No |
get_overviewread
Account totals (spend, View Content → Add to Cart, cost per ATC, leads — form vs website — and cost per lead, conversations), the daily series, campaigns and the top ads for a period, from the last sync.
get_breakdownsread
LIVE Meta call: performance for the period (or any since/until within Meta's 37 months — this one does not need the warehouse) broken down by age, gender, country, publisher_platform or device_platform, account-wide (cached ten minutes).