facebook-page-insights
Read Facebook Fanpage information, published posts, engagement counts, comments, reactions, and Page/Post Insights.
Connect this API to an AI agent Browse all specs
What you can do with facebook-page-insights via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /{pageId} |
getFacebookPage | Get detailed information for a Fanpage Method: GET Path: /{pageId} IMPORTANT: This function has 2 REQUIRED parameter(s) and 0 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - pageId: Numeric Facebook Page ID (digits only). Not an Instagram Business Account ID (often starts with 17841…). Pin this parameter per connection when installing the same template for multiple Fanpages on one agent. Query Parameters: REQUIRED: - fields: Comma-separated Page fields. Example: id,name,username,category,link,about,description,website,phone,followers_count,fan_count,verification_status,picture |
| GET | /{pageId}/published_posts |
listFacebookPagePosts | List posts published by a Fanpage Method: GET Path: /{pageId}/published_posts IMPORTANT: This function has 1 REQUIRED parameter(s) and 6 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - pageId: Numeric Facebook Page ID (digits only). Not an Instagram Business Account ID (often starts with 17841…). Pin this parameter per connection when installing the same template for multiple Fanpages on one agent. Query Parameters: OPTIONAL: - fields: Comma-separated Post fields. Keep the summary fields to receive total reactions and comments without loading every item. - limit: Maximum records per page. - after: Cursor returned in paging.cursors.after. - before: Cursor returned in paging.cursors.before. - since: Start of insights range as YYYY-MM-DD or Unix timestamp. With until, Meta allows at most 90 days per request. since is included in the first returned value. - until: End of insights range as YYYY-MM-DD or Unix timestamp. With since, at most 90 days per request. |
| GET | /{pageId}/insights |
getFacebookPageInsights | Read Page-level Insights Method: GET Path: /{pageId}/insights IMPORTANT: This function has 2 REQUIRED parameter(s) and 5 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - pageId: Numeric Facebook Page ID (digits only). Not an Instagram Business Account ID (often starts with 17841…). Pin this parameter per connection when installing the same template for multiple Fanpages on one agent. Query Parameters: REQUIRED: - metric: Comma-separated Page Insights metric names. Match period to the metric. Request fewer metrics if the call times out. Page metrics (typical period: day, week, days_28): - page_media_view — times content was played/displayed (replaces page_impressions). Optional breakdown is_from_ads, is_from_followers. - page_total_media_view_unique — unique media viewers (replaces page_impressions_unique / reach). - page_views_total — times the Page profile was viewed. - page_post_engagements — reactions, comments, shares on posts. - page_follows — current follower total (period day). - page_daily_follows_unique / page_daily_unfollows_unique. - page_total_actions — contact info and CTA button clicks. - page_video_views — video plays of at least ~3 seconds. - page_actions_post_reactions_total — daily reactions by type. Deprecated (do not use; invalid metric): page_impressions, page_impressions_unique, page_impressions_paid, page_fans, and other metrics listed in Meta deprecated Page Insights docs. OPTIONAL: - period: Aggregation period for the metric. Must be allowed for that metric: Page media/engagement often day|week|days_28; many post metrics are lifetime only. See metric description. - breakdown: Optional breakdown for supported metrics. page_media_view and post_media_view support is_from_ads and is_from_followers (comma-separated for multiple). - date_preset: Relative date range alternative to since/until. Do not combine with since/until in a conflicting way; prefer one style per request. - since: Start of insights range as YYYY-MM-DD or Unix timestamp. With until, Meta allows at most 90 days per request. since is included in the first returned value. - until: End of insights range as YYYY-MM-DD or Unix timestamp. With since, at most 90 days per request. |
| GET | /{postId} |
getFacebookPost | Get detailed information for a Page post Method: GET Path: /{postId} IMPORTANT: This function has 2 REQUIRED parameter(s) and 0 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - postId: Facebook Page post ID, commonly formatted as PAGE_ID_POST_ID. Obtain from listFacebookPagePosts. Do not pin unless locking one post. Query Parameters: REQUIRED: - fields: Comma-separated Post fields. Example: id,message,created_time,updated_time,permalink_url,full_picture,status_type,is_published,shares,comments.limit(0).summary(true),reactions.limit(0).summary(true) |
| GET | /{postId}/comments |
listFacebookPostComments | List comments on a Page post Method: GET Path: /{postId}/comments IMPORTANT: This function has 1 REQUIRED parameter(s) and 6 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - postId: Facebook Page post ID, commonly formatted as PAGE_ID_POST_ID. Obtain from listFacebookPagePosts. Do not pin unless locking one post. Query Parameters: OPTIONAL: - fields: No description - order: No description - filter: No description - limit: Maximum records per page. - after: Cursor returned in paging.cursors.after. - before: Cursor returned in paging.cursors.before. |
| GET | /{postId}/reactions |
listFacebookPostReactions | List reactions on a Page post Method: GET Path: /{postId}/reactions IMPORTANT: This function has 1 REQUIRED parameter(s) and 5 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - postId: Facebook Page post ID, commonly formatted as PAGE_ID_POST_ID. Obtain from listFacebookPagePosts. Do not pin unless locking one post. Query Parameters: OPTIONAL: - fields: No description - type: Optionally return only one reaction type. - limit: Maximum records per page. - after: Cursor returned in paging.cursors.after. - before: Cursor returned in paging.cursors.before. |
| GET | /{postId}/insights |
getFacebookPostInsights | Read Post-level Insights Method: GET Path: /{postId}/insights IMPORTANT: This function has 2 REQUIRED parameter(s) and 5 OPTIONAL parameter(s) REQUIRED parameters MUST be provided OPTIONAL parameters can be omitted if not needed Parameters: Path Parameters: REQUIRED: - postId: Facebook Page post ID, commonly formatted as PAGE_ID_POST_ID. Obtain from listFacebookPagePosts. Do not pin unless locking one post. Query Parameters: REQUIRED: - metric: Comma-separated Post Insights metric names. Match period to the metric (many post metrics are lifetime only). Post metrics (typical period: lifetime; some also support day): - post_media_view — times the post was played/displayed (replaces post_impressions). Optional breakdown is_from_ads, is_from_followers. - post_total_media_view_unique — unique media viewers for the post. - post_clicks / post_clicks_by_type — clicks without generating a story. - post_reactions_by_type_total — reactions by type. - post_video_views — video plays of at least ~3 seconds. - post_activity_by_action_type — stories created about the post. Deprecated (do not use): post_impressions, post_impressions_unique, post_engaged_users, and other deprecated Post Insights metrics. OPTIONAL: - period: Aggregation period for the metric. Must be allowed for that metric: Page media/engagement often day|week|days_28; many post metrics are lifetime only. See metric description. - breakdown: Optional breakdown for supported metrics. page_media_view and post_media_view support is_from_ads and is_from_followers (comma-separated for multiple). - date_preset: Relative date range alternative to since/until. Do not combine with since/until in a conflicting way; prefer one style per request. - since: Start of insights range as YYYY-MM-DD or Unix timestamp. With until, Meta allows at most 90 days per request. since is included in the first returned value. - until: End of insights range as YYYY-MM-DD or Unix timestamp. With since, at most 90 days per request. |
Usage guide
> **Authentication Request** > > Authentication requires a **Page Access Token** for a Page managed by the token owner. > *Note: This template is read-only and contains GET operations only.* --- ### **Required Permissions** To proceed, please ensure the following permissions are granted to your app: * `pages_show_list` * `pages_read_engagement` * `pages_read_user_content` * `read_insights` --- ### **How to Get a Page Access Token** Follow these steps using the **Meta Graph API Explorer**: 1. **Open Graph API Explorer** * Go to the [Meta Graph API Explorer](https://developers.facebook.com/tools/explorer/). * Select your Meta App from the **Meta App** dropdown in the right panel. 2. **Add Required Permissions** * In the **Permissions** section, click **Add a Permission**. * Add the following four permissions: * `pages_show_list` * `pages_read_engagement` * `pages_read_user_content` * `read_insights` 3. **Generate User Access Token** * Click **Generate Access Token**. * Log in to Facebook and select the Page(s) you want to manage. * Accept the requested permissions to return a short-lived **User Access Token**. 4. **Exchange for a Page Access Token** * In the **User or Page** dropdown, select the specific **Facebook Page** you want to access. * The token displayed in the **Access Token** field will automatically update to a **Page Access Token**. > **Note for Production:** Tokens generated via the Graph API Explorer are short-lived. For permanent or automated integrations, exchange your short-lived User Access Token for a **Long-Lived User Access Token** via the `oauth/access_token` endpoint, then query `/{page-id}?fields=access_token` to get a **Never-Expiring Page Access Token**.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “facebook-page-insights” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.