pages_read_engagement is the Facebook permission that lets an app read a Page’s content and insights: posts, comments, reactions and metrics. When it is missing you get a permission error on the Page, even though the user is an admin. The fix is to add the scope to the login request and grant it on the Page, then check the token with the debug tool.
This post is about reading Page data. It is the sibling of the posting scope, and the two get confused constantly. If you are chasing a write error instead, see the pages_manage_posts fix.
User logs in
|
v
App requests scopes: pages_show_list
pages_read_engagement <-- the one that bites
(pages_manage_posts if publishing)
|
v
User picks which Pages to grant
|
v
Token issued: user token
|
v
Exchange for Page token --> GET /{page-id}/insights OK
|
+-- scope missing? --> (#200) permission error
+-- Page unticked? --> error on that Page onlyWhat does the pages_read_engagement permission actually unlock?
It is the read access to what a Page publishes and how people respond to it.
With pages_read_engagement on a Page an app can read the Page’s posts, the comments on those posts, reactions, and the Page insights metrics that describe reach and engagement. It also lets the app read basic Page metadata that requires the scope rather than public data alone. In practice this is the scope behind every “show me how my Page did this week” screen.
What it does not do is write. No publishing, no replying, no editing. That is a separate permission, and a token can hold one without the other. Keeping the two roles separate is good design: an analytics dashboard should never hold the ability to post.
Why am I getting a pages_read_engagement missing permission error?
Almost always because the scope was never requested, or the user skipped that Page on the consent screen.
There are four common causes, and they look identical in the error body:
- Scope not requested. The login call asked for pages_show_list but not pages_read_engagement. The token cannot do what it was never granted.
- Page not selected. The scope is granted per Page. A user who administers five Pages can tick three on the consent dialog, and the token will fail on the other two.
- User token used where a Page token is needed. Some Page endpoints want the Page access token, not the user token, even with the right scope.
- Role missing. The person granting access is not an admin of that Page, or their role on the app does not allow the call before App Review.
The one that wastes the most time is the second. The app works in testing on Page A, then breaks on Page B for the same user, and the error text is the same. Test with the Page you actually need, not whichever one happened to be first.
How do I fix pages_read_engagement in the Graph API Explorer and app dashboard?
Add the scope in the dashboard, request it at login, then confirm it on the token before you touch the endpoint again.
- In the app dashboard, open the Facebook Login settings and confirm the app is requesting pages_read_engagement along with pages_show_list. The second one is what makes the Page picker appear.
- In the Graph API Explorer, pick your app, open the permissions dropdown and tick pages_read_engagement. Generate a user token and accept the dialog on the Page you are debugging.
- Paste that token into the Access Token Debugger under Tools. The Scopes line must contain pages_read_engagement. If it does not, the login request is wrong, not the endpoint.
- Exchange the user token for that Page’s Page access token, then repeat the failing call with the Page token.
- If it still fails and the debugger shows the scope, the problem is the Page role or the app’s review status, not the token.
Do this once per Page you support. A single debugging session on the wrong Page teaches nothing.
pages_manage_posts vs pages_read_engagement: which scope do you need?
Read versus write. Pick by what the app does, not by which error you hit first.
| Scope | What it allows | Typical app |
|---|---|---|
| pages_show_list | List the Pages the user manages, so they can pick one | Every Facebook integration |
| pages_read_engagement | Read posts, comments, reactions and Page insights | Analytics, inbox, reporting |
| pages_manage_posts | Publish, edit and delete Page posts | Schedulers, publishing tools |
| pages_read_user_content | Read content users post on the Page, such as visitor posts and posts by others | Moderation and community tools |
An app that publishes usually also wants pages_read_engagement, because you cannot show publish results without reading them back. The reverse is not true, and that matters. An analytics tool that requests only pages_read_engagement holds no write ability, which is easier to explain in a review and safer if the key leaks. For that reason Creator OS supports read only connections on its MCP server, where the API refuses writes: read only API keys for AI agents.
How do you request pages_read_engagement for App Review?
With a screen recording that shows a real user granting the scope and a real insights call returning data.
App Review exists to see the permission used for what you said it is used for. For pages_read_engagement, reviewers want:
- A written explanation of the feature that needs Page insights, in the app’s own words.
- A screencast starting at login, showing the consent dialog with the Page picker and the scope visible, then the screen in your app that displays the Page data.
- Test credentials or a test Page they can reach if your app is gated.
Request only the scopes the screen recording demonstrates. Asking for pages_read_engagement next to scopes you do not show is the fastest way to a rejection and a resubmission. If you also publish, submit the write scope with its own recording rather than one crowded video.
Why might a client encounter permission errors updating their business Facebook page?
Because “updating” mixes read and write, and each Page in a portfolio carries its own grant.
The usual sequence: an agency connects a client’s Page, the connection works, then the client adds a new Page or changes who manages the existing one, and the client’s analytics break while publishing still works, or the reverse. The token is fine. The grant on that specific Page is not.
Two habits prevent it. First, store which Page each account is and re-check the scope per account instead of per user. Second, when a client reports an error, ask which Page and which button. “Insights are blank” is a read scope problem. “It says the post failed” is a write scope problem. Those are two different fixes and guessing wastes a support cycle.
The same per Page logic applies on LinkedIn, where company page posting has its own access rules. That walkthrough is here: posting to LinkedIn company pages.
How Creator OS handles Page insights without posting access
Creator OS reads Page insights through the same scopes described above and keeps read and write separate at the connection level.
Facebook is one of the networks in Creator OS, alongside Instagram, TikTok, YouTube, X, LinkedIn, Threads, Reddit, Discord, Slack and WhatsApp, plus Skool. Analytics come back as per post analytics, daily account metrics, follower stats and best time to post. An AI agent talking to Creator OS over the hosted MCP server at https://mcp.creatoros.ca/mcp can call tools like get_post_analytics or get_daily_metrics and get the numbers without any ability to publish, if the connection was created read only.
In the CLI, the same read path is one command:
creatoros analytics:daily --platform facebook --from 2026-01-01 --to 2026-01-31Run that against a workspace whose Facebook Page is connected and you get the month’s daily metrics. Nothing in that command posts, replies or edits. If you want the agent to act on the numbers, for example to draft a post about the best performing topic, that is a separate write call made deliberately.
This split is why Creator OS is usable from Claude, ChatGPT, Cursor and other MCP capable apps: a read only connection has the read tools and the API refuses writes from it. The details are at https://www.creatoros.ca/docs/mcp and https://www.creatoros.ca/docs/authentication. You can also see these tools in action on the KevBuildsApps YouTube channel.
FAQ
How do I check if my token has pages_read_engagement?
Paste the token into the Access Token Debugger under Tools in the Graph API Explorer and read the Scopes line. If pages_read_engagement is absent, the login request never asked for it or the user did not grant it on that Page. Re-run the login with the scope ticked and confirm again before testing the endpoint.
Do I need App Review to use pages_read_engagement?
Only for people outside your app’s testers and admins. During development, users with a role on the app can grant the scope and call the endpoint. To serve real clients at scale you submit the scope for App Review with a screen recording of the feature that uses it.
Can pages_read_engagement read insights without pages_manage_posts?
Yes. Reading Page posts, comments and insights does not require the publishing scope. A token holding pages_show_list and pages_read_engagement can pull insights and cannot publish, which is the safer setup for a reporting tool or a read only AI connection.
Why does pages_read_engagement work in Graph API Explorer but not my app?
The Explorer can generate a token with scopes your app’s own login flow does not request. Compare the Scopes line from the Explorer token with the token your app actually receives, then add the missing scope to the login request. Also check that the app token was exchanged for the right Page’s Page access token.
What is the difference between pages_read_engagement and pages_read_user_content?
pages_read_engagement covers the Page’s own posts, comments, reactions and insights. pages_read_user_content covers content that users post on the Page, such as visitor posts and posts by others. A moderation tool usually needs the second, a reporting tool the first, and many apps end up requesting both.
Get started with Creator OS
If you would rather not maintain the Facebook scope dance yourself, connect the Page to Creator OS and read the analytics there, with the same numbers available to your AI agent through the MCP server or the CLI.
Creator OS plans start at $14.99/month for 11 platforms plus Skool, with the API, the MCP server and the CLI included. Create an account at https://www.creatoros.ca/sign-up. For the full request shapes, including how platforms and options are passed in a post, see https://www.creatoros.ca/docs/api/posts, and for the video walkthroughs, the launch video.
Get started for $0
Free trial for new subscribers. Cancel anytime.