meta-page-stats 0.1.0

Local diagnostic app and CLI for Meta Page insights and post statistics.

Meta Page Stats

Local browser app for retrieving Facebook Page statistics across a selected date range.

The app is intentionally diagnostic-heavy: it identifies whether the token is a User or Page token, shows which Graph API endpoints were tested, reports metric-by-metric Page Insights status, and explains Meta permission failures without hiding partial data. Repeated Graph API responses are cached in server memory for faster reruns. Use the Clear cache button in the browser to discard cached responses. Long downloads show a progress bar with elapsed time while the synchronous Graph API request is running. The Dark/Light button switches both the app and chart theme; the choice is saved in your browser.

Run

python3 -m pip install -e .
meta-page-stats --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000.

The in-memory cache defaults to 6 hours. Override it before starting the server:

export META_STATS_CACHE_TTL_SECONDS=900
meta-page-stats

You can paste an access token into the app, or set one before starting the server:

export META_PAGE_ACCESS_TOKEN='EAAB...'
meta-page-stats

Do not put your App Secret in this app. The app only needs a User or Page access token.

App ID and App Secret

You do not enter the App ID or App Secret in the stats UI.

• Use the App ID when selecting your app in Meta's Graph API Explorer or in a Facebook Login flow.
• Keep the App Secret private. It is only for server-side OAuth/token exchange, such as exchanging a short-lived User token for a long-lived token.
• Put the resulting User or Page access token into the app's Access token field.

If "Load pages" says /me/accounts does not exist, the token is probably already a Page access token. In that case, enter that Page's numeric ID and run the query directly.

Meta access

For Page insights and posts, the token normally needs:

• pages_show_list
• pages_read_engagement
• read_insights

If you paste a User token, the app can list pages through /me/accounts and resolve the matching Page access token server-side. In Meta development mode, the Facebook user must usually have a role on the Meta app and access to the Page. For production access outside your app roles, Meta may require App Review for the permissions.

To verify a token before using the app, run this in Graph API Explorer with the same token:

GET /PAGE_ID/posts?fields=id,created_time,message&limit=1
GET /PAGE_ID/insights?metric=page_post_engagements&period=day

If Graph API Explorer returns (#10) pages_read_engagement, regenerate the token and make sure the Facebook permission dialog grants the app access to that specific Page.

If Graph API Explorer also returns (#10) for GET /PAGE_ID/posts?fields=id,created_time,message&limit=1, the local app cannot make Posts work. That is a Meta permission, Page grant, or App Review issue for pages_read_engagement / Page Public Content Access.

If Graph API Explorer returns (#100) The value must be a valid insights metric, remove or rename that metric. For Page reactions, use page_actions_post_reactions_total; page_post_reactions_total is not a valid Graph API metric name. For Page followers, use page_follows.

The default Page metric list uses the newer post-November-2025 replacements such as page_media_view and page_follows, while the Post tab keeps older metrics available too and skips unsupported metrics per post.

In the browser, check:

• Token diagnostics for token type, effective Page, endpoint checks, and the next action.
• Metric statuses for ok, unsupported, no_values, or permission_error per Page metric.
• Notice for the plain-English reason when a query returns zero rows.

Official references:

• Graph API Insights
• Pages access tokens
• Graph API Explorer

CLI export

The CSV exporter is installed as a command:

meta-page-post-export --page-id 1234567890 --since 2026-04-22 --until 2026-05-19 --out facebook_post_stats.csv

The old direct commands python3 app.py and python3 export_meta_page_post_stats.py are kept as compatibility launchers for local checkout use. New installs should use meta-page-stats and meta-page-post-export.

Package build

Build and validate the package locally:

python3 -m pip install build twine
python3 -m build
python3 -m twine check dist/*

Upload to TestPyPI when you have credentials configured:

python3 -m twine upload --repository testpypi dist/*

Then test an install from TestPyPI:

python3 -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ meta-page-stats
meta-page-stats --host 127.0.0.1 --port 8000

Do not publish access tokens, App Secrets, cache data, generated CSV exports, or local screenshots. The package uses a src/ layout and excludes local build artifacts by default.