Reel Insights
facebook_reel_insightsRetrieve Facebook Reel metrics (plays, watch time, likes, social actions) from the /video_insights edge using the numeric video ID, avoiding the post-ID endpoint that cannot reach Reel data.
Instructions
Read Graph insights for one Reel from /{video-id}/video_insights — the edge Reel metrics actually live on, which facebook_post_insights cannot reach. Takes the VIDEO id (digits only, as returned by facebook_create_reel), NOT a "{page-id}_{post-id}" post ID. Same compact shape as the other insights tools: flat rows plus one summary per metric, or totals only with aggregate:true. The default period is "lifetime", because plays and watch time are cumulative counters rather than a daily series. Metric names are their own vocabulary — page/post names do not transfer — and Meta's reference lists blue_reels_play_count, post_video_avg_time_watched, post_video_view_time, post_video_likes_by_reaction_type and post_video_social_actions among others; they are examples, not a whitelist, so a name Graph never mentions is reported as unavailable rather than silently dropped. Empty series usually mean the wrong ID, a Reel that is not PUBLISHED yet, or the usual insights lag — the result says which to check.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | Start of the window as a calendar date "YYYY-MM-DD" (inclusive, Page timezone). Omitted ⇒ Graph's own default window. The since..until span may not exceed 90 days per call (checked before the request); read longer histories in slices. | |
| until | No | End of the window as a calendar date "YYYY-MM-DD". Each returned `date` is the END of the period the value covers, so a window reaching today ends in a partial, still-being-computed bucket. Omitted ⇒ today. | |
| period | No | Aggregation window Graph applies per data point. "day" is a daily series (the Page default); "lifetime" is one cumulative value per metric (the post default); "week"/"days_28" are rolling windows; "month" is calendar-monthly; "total_over_range" collapses since..until into a single value. Not every metric supports every period — a metric queried with an unsupported period comes back empty, which the notes call out. | |
| metrics | Yes | Graph insights metric names to read, e.g. ["page_media_view","page_follows"] (1-20 per call; trimmed and lower-cased). Names are Graph-version dependent and Meta renamed most of them in the 2024-09, 2025-11 and 2026-06 waves: pre-wave names such as "page_impressions" or "page_fans" are dropped before the request and answered with their replacement instead of an error. Graph fails the WHOLE call when one surviving name is invalid, so isolate a suspect name by requesting it alone. | |
| profile | No | Page profile key (e.g. "brand-a") or a raw Page ID. Omitted ⇒ the default Page (FB_PAGE_ID). | |
| max_rows | No | Lower the per-point row cap for this call (1-250; the default and the ceiling are both 250 — this argument can only shrink it). Rows past the cap are dropped and the result reports how many; prefer aggregate:true over a tiny cap when you only need totals. | |
| video_id | Yes | The Reel to read, as its VIDEO id — the `videoId` returned by facebook_create_reel (also echoed by facebook_get_video_status). A "{page-id}_{post-id}" value is a post, not a video, and does not resolve on the /video_insights edge. The Reel must belong to the resolved Page, whose token authorizes the read. | |
| aggregate | No | True ⇒ return per-metric totals only (period, points, total, first/last boundary) and NO per-point rows. Use it for wide windows or many metrics: it is the cheapest way to stay inside the result budget when a daily series would otherwise be truncated. |