Meta Ads Library API: What It Returns and What It Doesn't

What does the Meta Ads Library API return?

The Meta Ads Library API returns advertiser identity, ad creative, region targeting, run dates, and (for political/social ads only) spend ranges + impression ranges. It does NOT return: CTR, conversion rate, custom audience overlap, A/B variant lineage, or any data on commercial ads' performance. CommonWealth Ops's pipeline reads the same surface — the walls below are the structural limits anyone integrating against this API will hit.

The official documentation lists 15+ fields. In practice for an operator building intelligence:

• `ad_creation_time` / `ad_delivery_start_time` / `ad_delivery_stop_time` — the lifecycle dates. `stop_time` may be NULL while the ad is still running.
• `page_id` / `page_name` — the advertiser identity.
• `ad_creative_bodies` / `ad_creative_link_titles` / `ad_creative_link_descriptions` — the text content of the ad.
• `ad_snapshot_url` — a stable URL to a screenshot of the ad as Meta archived it. Useful for visual inspection.
• `languages` / `publisher_platforms` — Facebook, Instagram, Messenger, Audience Network distribution flags.
• `spend` / `impressions` / `demographic_distribution` — POLITICAL/SOCIAL ADS ONLY. Returns range buckets ($100-$499, $500-$999, etc.) for spend; impression ranges similarly bucketed.

What the API deliberately doesn't return

Five walls every developer integrating against this API will hit:

Wall 1 — Commercial ads have no performance data. All of `spend`, `impressions`, `demographicdistribution`, `deliveryby_region` are stripped from the response for non-political/non-social ads. This is by policy — Meta exposes spend transparency for politically-relevant ads under the EU Digital Services Act and U.S. political-ad rules, not for commercial DTC ads.

Wall 2 — No conversion or CTR data ever. The platform does not expose conversion rates, click-through rates, cost-per-action, or any post-impression behavior data through the public API for any ad type. This is a fundamental design choice — the platform monetizes those metrics through its Ads Manager API which requires the brand's own access permissions.

Wall 3 — No A/B variant lineage. When a brand runs 5 ads with minor variations, the API returns 5 separate ads with no field linking them as variants of the same test. Operators have to infer variant relationships from creative-text similarity heuristics — error-prone and language-dependent.

Wall 4 — No custom audience or lookalike data. The audience targeting Meta exposes is region + age/gender (only for political/social ads). Custom audiences, lookalikes, and behavioral targeting are entirely walled.

Wall 5 — Once-active ads disappear. For commercial ads, the API returns only currently-active ads. An ad pulled yesterday is gone from the API today. Building a historical record requires capturing weekly and persisting locally — which is exactly what the CommonWealth Ops capture pipeline does for fitness, skincare, and supplements niches.

What the practical pipeline looks like for an operator

Building against the Meta Ads Library API for intelligence work requires four structural decisions:

Decision 1 — Token strategy. Personal user token for development; system user token for production. The system user setup takes ~30 minutes through the Meta Business Manager and is required for any sustained reading volume.

Decision 2 — Rate limit handling. 200 calls/hour/user means a 30-niche capture pass needs careful queue management. The CommonWealth Ops pipeline uses exponential backoff + a Redis-based rate-limit budget tracker — patterns documented in our how-CommonWealth-Ops-collects-intelligence post.

Decision 3 — Pagination correctness. The API's page tokens are NOT idempotent across calls — if a new ad enters the result set between pages, the pagination shifts. Capturing a full result set requires either (a) accepting some duplicate / missed rows in fast-moving niches, or (b) running the full pagination loop inside a single rate-limit budget allocation. CommonWealth Ops accepts the duplicate / missed risk and de-duplicates on `ad_id` at the database layer.

Decision 4 — Persistence schema. The API's flat JSON response needs normalization into a relational schema for query work. The CommonWealth Ops `scrapedads` table has 17 columns including the `viewsband` binning added in Sprint 25, `spendrange` left NULL for commercial ads (Meta wall), and Whisper-transcribed `hooktext` for the video creative subset.

How CommonWealth Ops uses the API in production

CommonWealth Ops captures Meta Ads Library data weekly for fitness, skincare, and supplements niches across multiple geographies. The current capture surfaces brands like Flipkart, BigMuscles Nutrition, Lazada, Hardyn, Amazon India, Tori Repa, Angê, Jewel by ZERO, MyFitness, Rogue Fitness Europe, WHOOP, and Freeletics in fitness; HK Vitals, Purplle beauty, La Roche-Posay Indonesia, BEARDO for Men, Lotus Botanicals, Pilgrim, Clinikally, and the Plix franchise + Pilgrim franchise + Mamaearth franchise variants in skincare.

The captured set lands in a normalized PostgreSQL schema. Subscribers receive the weekly per-niche intelligence report derived from the persisted history — which is the value-add the raw API doesn't provide.

The methodology is fully documented in our how-CommonWealth-Ops-collects-intelligence post. Developers integrating their own pipelines against the API should pair the official documentation with the CommonWealth Ops wall documentation in our why-ad-longevity-beats-ad-spend post for the structural limits the docs don't surface clearly.

See pricing →