Expose full Meta Pixel funnel, native breakdowns and creative metadata in /ads/tree

Following the recent addition of the top-level video retention fields (huge win, thanks) — there are still several native Meta Insights fields that we have to extract by string-matching inside metrics.actions[] / metrics.actionValues[]. This is fragile: Meta occasionally renames action types, and summing actions[] at campaign / ad set level corrupts the values (same reason you isolated videoAvgTimeWatchedActions as a dedicated field).

We'd like the same treatment for the following.

1. Full Pixel funnel as top-level fields (highest priority)

• landingPageViews — landing_page_view

• viewContent — view_content / offsite_conversion.fb_pixel_view_content

• addToCart + addToCartValue

• initiateCheckout

• purchases + purchaseValue

• leads

Why: these are the core conversion events Meta exposes. Reading purchases and purchaseValue out of an array is the single most error-prone thing in the current response — one rename from Meta and ROAS goes to zero silently.

2. Click metrics as top-level fields

• linkClicks

• outboundClicks

• uniqueLinkClicks

Why: unique link clicks is the only way to compute a deduplicated CTR when frequency is high. It's a native Meta field and can't be reconstructed from actions[].

3. Engagement metrics as top-level fields

• postEngagements, postReactions, comments, shares, pageEngagement

Why: same rationale — dedicated fields, no array parsing, no rename risk.

4. Native Meta breakdowns (high priority)

Meta's Insights API supports breakdowns=publisher_platform, placement, age, gender, device_platform, country, region. Today /ads/tree returns totals only.

Ideal: an optional breakdowns query param on /ads/tree (and /ads, /ads/campaigns) that returns a breakdowns[] array per ad with the same metrics object per segment.

Priority for us: placement → age + gender → device_platform → country.

Why: without breakdowns, an ad shows only its aggregate performance. The whole diagnostic value of Meta Insights is being able to see where the performance concentrates (e.g. Reels vs Right Column, mobile vs desktop). Right now we have to hit Meta Graph directly to get this.

5. Configurable attribution window

Ability to request 1d_click, 7d_click, 1d_view, 7d_click_1d_view separately — either as a query param (?attribution=1d_click) or as parallel fields in the response.

Why: Meta's default mixes click + view attribution. Being able to isolate the click window is a standard Meta Insights capability that isn't currently exposed.

6. Creative metadata

• videoPermalinkUrl / videoSourceUrl (HD)

• thumbnailUrlHD (256px+ — current thumbnails are ~64px)

• creativeType — explicit enum: VIDEO / IMAGE / CAROUSEL / DPA / COLLECTION

• adPreviewUrl

Why: to render an ad in a UI today we have to make additional Meta Graph calls for playable video URLs and hi-res thumbnails. Bundling this into /ads/tree removes those extra calls and the rate-limit pressure they generate.

7. Extra video metrics missed in the last batch

• videoContinuous2SecWatchedActions — Meta's official "2 continuous seconds" metric (different from video_view)

• costPerThruplay

• costPer2SecContinuousVideoView

Suggested implementation

Same pattern as the video retention batch:

• Top-level key inside metrics (not inside metrics.actions) so aggregation is dedicated and safe.

• 0 for non-Meta platforms / non-applicable ads.

• Included in metrics.daily[] when timeIncrement=1 is requested.

• Breakdowns opt-in via query param, returned as metrics.breakdowns.placement[], etc.

Alternative

Add a generic insightsFields query param that accepts raw Meta Insights field names and passes them through. That way integrators can unblock themselves without waiting for each field, and it future-proofs against Meta adding new ones.