# Facebook Page Insights API: Metrics, Permissions, Limits

How to call the Facebook Page Insights API: the insights edge, read_insights, period and 90-day limits, and which metrics Meta deprecated in 2024 and 2025.

Canonical page: https://www.tryadeli.com/blog/facebook-page-insights-api
Last updated: 2026-10-19

By Mika Reyes, Co-founder, Adeli. Published 2026-10-19.

## The short answer

The Facebook Page Insights API is the insights edge of the Graph API. Call GET /{page-id}/insights or /{post-id}/insights with a Page access token, the read_insights and pages_read_engagement permissions, and a metric list. Requests cover at most 90 days and data goes back two years. Meta removed page_impressions and page_fans in November 2025; use page_media_view and page_follows. Adeli returns 28-day Page Insights in one call.

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](https://www.tryadeli.com/blog/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](https://www.tryadeli.com/blog/facebook-page-access-token) walks through getting one that doesn't expire.
- **The ANALYZE task.** Meta's [insights reference](https://developers.facebook.com/docs/graph-api/reference/insights) 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:

| Permission | What Meta says it allows | Depends on |
|---|---|---|
| `read_insights` | Read the Insights data for Pages, apps, and web domains the person owns | `pages_read_engagement`, `pages_show_list` |
| `pages_read_engagement` | Read content posted by the Page, followers data, and metadata and other insights about the Page | `pages_show_list` |

Source: Meta's [permissions reference](https://developers.facebook.com/docs/permissions). For Pages your app doesn't own, both need **Advanced Access**, which means Business Verification and App Review. Our [Meta app review guide](https://www.tryadeli.com/blog/meta-app-review-time) 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.

```bash
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:

```bash
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](https://developers.facebook.com/docs/graph-api/reference/insights):

| Metric | What it measures | Periods |
|---|---|---|
| `page_media_view` | Times the Page's content (videos, posts, stories, and ads) was played or displayed | day, week, days_28 |
| `page_total_media_view_unique` | Unique viewers of the Page's content | day, week, days_28 |
| `page_post_engagements` | Times people engaged with the Page's posts through reactions, comments, shares, and more | day, week, days_28 |
| `page_views_total` | Views of the Page's profile, logged in and logged out | day, week, days_28 |
| `page_follows` | Followers of the Page | day |
| `post_media_view` | Times one post was played or displayed | lifetime |
| `post_total_media_view_unique` | Unique viewers of one post | lifetime |
| `post_reactions_by_type_total` | A post's reactions, split by type | lifetime |
| `post_clicks` | Clicks anywhere in a post that don't generate a story | lifetime |

`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](https://developers.facebook.com/docs/platforminsights/page/deprecated-metrics) page; these are the ones most integrations used:

| Deprecated | Date | Meta's alternative |
|---|---|---|
| `page_impressions` | 2025-11-15 | `page_media_view` |
| `page_impressions_paid` | 2025-11-15 | `page_media_view` with the `is_from_ads` breakdown |
| `page_impressions_viral`, `page_impressions_nonviral` | 2025-11-15 | None |
| `page_fans` | 2025-11-15 | `page_follows` |
| `page_fans_city`, `page_fans_country` | 2025-11-15 | `page_follows_city`, `page_follows_country` |
| `page_fan_adds`, `page_fan_removes` | 2025-11-15 | None |
| `post_impressions` | 2025-11-15 | `post_media_view` |
| `post_impressions_fan` | 2025-11-15 | `post_media_view` with the `is_from_followers` breakdown |
| `page_impressions_unique` | 2025-06-15 | `page_total_media_view_unique` |
| `post_impressions_unique` | 2025-06-15 | `post_total_media_view_unique` |
| `page_engaged_users`, `page_consumptions`, `page_positive_feedback`, `post_activity` | 2024-03-14 | None |

Meta's [announcement of the November change](https://developers.facebook.com/blog/post/2025/08/15/page-insights-api-updates/) 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](https://www.tryadeli.com/product/facebook) 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](https://www.tryadeli.com/docs/api/analytics/facebook-page-metrics):

```bash
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:

| Adeli field | Meta metric |
|---|---|
| `views` | `page_media_view`, summed over the window |
| `engagements` | `page_post_engagements`, summed |
| `pageViews` | `page_views_total`, summed |
| `followers` | `page_follows` on the latest day Meta reported |
| `daily` | Daily views, oldest first |

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](https://www.tryadeli.com/social-media-analytics-api) 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**.

## Frequently asked questions

### Is page_impressions deprecated?

Yes. Meta's deprecated metrics list says page_impressions, its paid, viral, and nonviral variants, and the post_impressions family were deprecated for all API versions on November 15, 2025. Meta names page_media_view as the alternative for Pages and post_media_view for posts. Calls to a removed metric return an invalid metric error.

### What replaced page_fans in the Graph API?

Meta lists page_follows as the alternative to page_fans, and page_follows_city and page_follows_country for the location breakdowns. Page_fan_adds and page_fan_removes have no replacement. All of these were deprecated on November 15, 2025.

### Why does the Page Insights API return no data?

Check four things. Meta only reports insights for Pages with 100 or more likes, demographic metrics need 100 or more people, the token has to come from someone who can perform the ANALYZE task on the Page, and most metrics update once every 24 hours, so today's numbers may not exist yet.

### How far back can I get Facebook Page insights?

Meta keeps the last two years of insights. A single request with since and until can cover at most 90 days, so a two-year backfill takes about nine requests per metric set.

## Related Adeli pages

- [Social Media Analytics API](https://www.tryadeli.com/social-media-analytics-api.md): Adeli's analytics API: Instagram, TikTok, Facebook Page, and YouTube insights endpoints, plus per-post engagement on every post an account has made.
- [Facebook API for Developers](https://www.tryadeli.com/product/facebook.md): Publish, schedule, and read analytics for Facebook Pages through one API. Adeli owns the Facebook developer app, token refresh, and Meta review. Free to start.
- [All posts on the Adeli blog](https://www.tryadeli.com/blog.md)

## About the author

Mika Reyes is the CEO behind Adeli and a tech and AI content creator. She was previously co-founder and CEO of Parallax, which was acquired by Phantom, and a product lead at LinkedIn. She is a Forbes 30 Under 30 honoree.