Page Insights
facebook_page_insightsFetch Facebook Page engagement and reach metrics over a date range, returning totals or per-date rows while handling renamed metric names and flagging missing permissions or eligibility limits.
Instructions
Read Graph insights for one Page in a compact flat shape: one row per metric per data point ({metric, date, value}, plus breakdown for by-action-type metrics) and one summary per metric (period, points, total). Set aggregate:true for totals only. The window is since/until calendar dates, at most 90 days per call. Metric names renamed by the 2024-09 / 2025-11 / 2026-06 waves are answered with their replacement instead of a Graph error, and a metric Graph accepts but has no data for is reported separately from a name Graph does not know. Empty series usually mean the eligibility floor (a Page under 100 followers) or a token missing read_insights + the ANALYZE Page task — not zero engagement; the result says which. Reel metrics are NOT available here: they live on /{video-id}/video_insights — use facebook_reel_insights for those.
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. | |
| 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. |