Post Insights
facebook_post_insightsFetch insights for a single published Facebook post, including views, clicks, reactions, and video metrics, with per-metric summaries or aggregate totals for performance analysis.
Instructions
Read Graph insights for one published post (post_media_view, post_clicks, post_reactions_by_type_total, video metrics, ...) in the same compact flat shape as facebook_page_insights: rows plus per-metric summaries, or totals only with aggregate:true. The default period is "lifetime" — one cumulative value per metric. Post metrics lag minutes to hours after publishing, so empty series on a fresh post are normal and are flagged as such rather than reported as zeros. Reel metrics are NOT reachable through this tool: they live on /{video-id}/video_insights, a different edge — a Reel ID here returns empty series, never Reel numbers. Use facebook_reel_insights with the VIDEO id instead.
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. | |
| post_id | Yes | The published post to read, as Graph's "{page-id}_{post-id}" ID (as returned by facebook_list_posts / facebook_get_post). Permalink URLs are rejected. The post must belong to the resolved Page, whose token authorizes the read. | |
| 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. | |
| 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. |