Facebook Page Insights API: Metrics, Permissions, Limits

The Facebook Page Insights API is the insights edge of Meta's Graph API. You call GET /{page-id}/insights for Page-level metrics or GET /{post-id}/insights for a single post, pass the metrics you want, and authenticate with a Page access token that carries the read_insights and pages_read_engagement permissions. Meta caps each request at 90 days, keeps two years of history, and deprecated a large set of metrics in 2024 and 2025, so most tutorials written before then call metrics that no longer exist.

This guide covers the request, the permissions, the period and date rules, and the current metric names. It's part of our Facebook Graph API series.

What do you need before you start?#

• A Page access token. Page Insights calls act as the Page, so a user token won't do. Our Facebook Page access token guide walks through getting one that doesn't expire.
• The ANALYZE task. Meta's insights reference says the token has to come from a person who can perform the ANALYZE task on the Page.
• Two permissions, plus the one they depend on:

Source: Meta's permissions reference. For Pages your app doesn't own, both need Advanced Access, which means Business Verification and App Review. Our Meta app review guide covers what that takes.

How do I call the Facebook Page Insights API?#

Send a GET to the Page's insights edge with a comma-separated metric list. Meta's reference shows two forms: one metric in the path, or several in the metric parameter.

curl -G "https://graph.facebook.com/v26.0/$PAGE_ID/insights" \
  --data-urlencode "metric=page_media_view,page_post_engagements,page_views_total" \
  --data-urlencode "period=day" \
  --data-urlencode "since=2026-09-01" \
  --data-urlencode "until=2026-09-28" \
  --data-urlencode "access_token=$PAGE_TOKEN"

The response has a data array with one object per metric. Each object carries name, period, and a values array of { value, end_time } pairs, one per day for period=day.

Leaving out metric is an error. Meta's reference says the call fails with error 3001, subcode 1504028.

How do I get insights for a single Facebook post?#

Call the same edge on the post ID. Post metrics mostly use period=lifetime, so you don't pass a date range:

curl -G "https://graph.facebook.com/v26.0/$POST_ID/insights" \
  --data-urlencode "metric=post_media_view,post_total_media_view_unique,post_reactions_by_type_total,post_clicks" \
  --data-urlencode "access_token=$PAGE_TOKEN"

The post ID is the id you got back when you published to /{page-id}/feed, in the form {page-id}_{post-id}. Meta notes that Reel interactions aren't included in these figures, and that several video metrics are accurate only for the Page that created the video.

Which Page Insights metrics still work?#

Use the "media view" and "follows" metrics. These are the current names for the figures most dashboards need, taken from Meta's insights reference:

page_media_view and post_media_view accept the is_from_ads and is_from_followers breakdowns, which is how you split paid from organic now that the _paid and _organic metrics are gone.

Which Page Insights metrics did Meta deprecate?#

Meta deprecated three batches in 2024 and 2025, for all API versions. Calling any of them returns an invalid metric error. The full list is on Meta's deprecated Page Insights metrics page; these are the ones most integrations used:

Meta's announcement of the November change says impressions was replaced by views to match the Facebook app and Meta Business Suite, and page fans went because the classic Pages Insights tab was retired.

If your dashboard broke in late 2025, this is the likely cause. Swap each deprecated name for its alternative, and expect the new numbers not to line up exactly with the old ones, because views and impressions are counted differently.

What period and date limits apply?#

Each metric supports only some periods, and a request with since and until can span 90 days at most. The rules from Meta's reference:

• Periods. The edge accepts day, week, days_28, month, lifetime, and total_over_range, but each metric lists the ones it supports. Page metrics mostly take day, week, or days_28; post metrics mostly take lifetime.
• 90 days per request. Meta's wording: "Only 90 days of insights can be viewed at one time when using the since and until parameters."
• Two years of history. Anything older isn't available, and lifetime covers that window too.
• date_preset as a shortcut. Values such as yesterday, last_7d, last_28d, and last_90d replace since and until.
• Daily updates. Most metrics refresh once every 24 hours. Metrics marked with an asterisk in Meta's reference refresh several times a day.
• Minimum audience. Insights exist only for Pages with 100 or more likes, and demographic breakdowns need 100 or more people.

For a two-year backfill, loop in 90-day windows and store each window's results. Meta's breakdowns return only non-zero values, so treat a missing row as zero rather than as an error.

How does Adeli return Facebook Page Insights?#

Adeli returns a Page's details, recent-post engagement, and 28-day Page Insights in one request. Adeli's Facebook API holds the Meta app, carried Meta's review, and manages each connected Page's token, so you skip the permissions, the metric names, and the deprecation tracking above. The endpoint is Facebook Page metrics:

curl -G "https://app.tryadeli.com/api/v1/analytics/facebook/page-metrics" \
  -H "Authorization: Bearer $ADELI_API_KEY" \
  --data-urlencode "accountId=$ACCOUNT_ID"

The insights object in the response is built on the current metrics:

What we ran into while building it:

• A missing permission comes back as a status. If a Page was connected without read_insights, insights comes back null with insightsUnavailable: "permission_missing", and the rest of the response still returns. Reconnecting fixes it.
• analyze_task_missing is a different problem. Meta refused because the person who connected the Page can't view its insights, so a Page admin with analytics access has to reconnect.
• null is not 0. A figure Meta didn't report comes back null. Small or new Pages often have none yet.

Per-post Facebook insights aren't part of Adeli's v1 API. The same API key also reads Instagram, TikTok, and YouTube analytics and publishes to Facebook, Instagram, TikTok, YouTube, X, and Bluesky. A Facebook Page counts as one connected account, and your first 3 connected accounts are free.