> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/social-media/facebook-page-insights.md).

# Facebook Page Insights

Export Facebook Page Insights post performance, reach, and engagement metrics to Google Sheets, BigQuery, or Looker Studio via Coupler.io—automated, no code nee

Facebook Page Insights gives you detailed performance data about your Facebook page, posts, reels, and videos. With Coupler.io, you can automatically export this data to Google Sheets, Excel, BigQuery, Looker Studio, or AI destinations like Claude and ChatGPT—no code required.

## Why connect to Coupler.io?

* **Automate data exports** — Pull page and post performance data on a schedule without manual downloads
* **Multiple report types** — Choose from page overview, performance insights, audience demographics, post lifetime performance, reel metrics, and video daily performance
* **Flexible filtering** — Filter by date range, page, and post creation dates to get exactly the data you need
* **Combine with other data** — Use Join or Append transformations to combine Facebook insights with data from Instagram Insights, Facebook Ads, or other sources for deeper analysis
* **Send to AI** — Export data directly to Claude, ChatGPT, or Gemini to analyze trends and generate insights

## Prerequisites

* A Facebook business account with a page you manage or have admin access to
* Permission to access Page Insights (admin, editor, or analyst role on the page)
* A destination to send data (Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination)

## Quick start

{% hint style="success" %}
**Tip:** Start by exporting page general overview or performance insights to see your top metrics. Then add post or video performance reports in separate data flows if you need granular post-level data.
{% endhint %}

{% stepper %}
{% step %}
**Sign in with your Facebook account.** Click the Facebook Page Insights source and select "Sign in with Facebook." You'll be prompted to authorize Coupler.io to access your page data. Approve the connection and return to Coupler.io.
{% endstep %}

{% step %}
**Choose a report type.** Select one of the available report types: Page general overview, Page performance insights, Page audience daily snapshot, Post lifetime performance, Reels lifetime performance, or Video daily performance.
{% endstep %}

{% step %}
**Select your page(s).** Choose the Facebook page(s) you want to pull data from. You can select multiple pages in a single data flow and use the Append transformation to combine data from all of them.
{% endstep %}

{% step %}
**Set your date range (if applicable).** Depending on your report type, use the date picker to set start and end dates. Leave these blank to pull all available historical data.
{% endstep %}

{% step %}
**Choose metrics and dimensions.** Select the specific metrics and dimensions you want to include. For example, select "Followers" and "Impressions" for page overview, or "Engagement" and "Reach" for post performance.
{% endstep %}

{% step %}
**Pick your destination.** Choose where to send your data: Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like Claude or ChatGPT.
{% endstep %}

{% step %}
**Run the data flow.** Click "Run" to execute a manual test. Once it completes successfully, you can schedule it to run automatically.
{% endstep %}
{% endstepper %}

## Available report types

| Report Type                  | What it includes                                    | Best for                                                          |
| ---------------------------- | --------------------------------------------------- | ----------------------------------------------------------------- |
| Page general overview        | All available page metrics and dimensions           | Daily monitoring of followers, reach, impressions, and engagement |
| Page performance insights    | Engagement, reach, impressions, and custom metrics  | Analyzing which content types drive performance                   |
| Page audience daily snapshot | Daily audience demographics (age, gender, location) | Understanding who follows your page                               |
| Post lifetime performance    | Metrics for individual posts published to your page | Comparing post performance and identifying top performers         |
| Reels lifetime performance   | Metrics for reels published to your page            | Measuring reel performance (views, engagement)                    |
| Video daily performance      | Daily metrics for videos published to your page     | Tracking video views and engagement over time                     |

## Facebook Page Insights data overview

Facebook Page Insights provides a range of metrics and dimensions across different report types. The data available depends on which report you select.

## Report types and available metrics

| Report Type                  | Dimensions                           | Key Metrics                                               | Date Range                    |
| ---------------------------- | ------------------------------------ | --------------------------------------------------------- | ----------------------------- |
| Page general overview        | Page name, date                      | Followers, impressions, reach, engagement, clicks         | Configurable (start/end date) |
| Page performance insights    | Post type, date                      | Reach, impressions, engagement, clicks, video plays       | Configurable (start/end date) |
| Page audience daily snapshot | Age, gender, location, country       | Follower count by demographic                             | Configurable (start/end date) |
| Post lifetime performance    | Post ID, post content, creation date | Impressions, reach, engagement, reactions, clicks, shares | Filtered by creation date     |
| Reels lifetime performance   | Reel ID, creation date               | Views, engagement, shares (limited by API)                | Filtered by creation date     |
| Video daily performance      | Video ID, day, creation date         | Views, watch time, engagement                             | Configurable (start/end date) |

## Common metrics

#### Engagement metrics

* **Engagement** — Total reactions, comments, and shares
* **Engagement reactions** — Broken down by reaction type (Like, Love, Haha, Wow, Sorry, Angry)
* **Engaged users** — Count of unique users who engaged
* **Post clicks** — Total clicks on the post (excluding reactions)
* **Post shares** — Number of shares (via API where available)

#### Reach and impressions

* **Reach** — Unique users who saw your content
* **Impressions** — Total number of times your content was displayed
* **Paid reach** — Unique users reached via paid promotion
* **Organic reach** — Unique users reached through organic distribution

#### Video and reel metrics

* **Video views** — Total video plays
* **Video watch time** — Total minutes watched
* **Video average view duration** — Average watch time per video
* **Reel views** — Total reel plays
* **Reel engagement** — Reactions, comments, shares on reels

#### Audience metrics

* **Followers** — Total page followers
* **Fan adds** — New followers during the period
* **Fan removes** — Followers lost during the period
* **Age** — Follower age ranges (13-17, 18-24, 25-34, etc.)
* **Gender** — Breakdown by male, female, or unknown
* **Country** — Geographic location of followers
* **City** — City location (where available)

## Use cases by role

{% tabs %}
{% tab title="Social Media Managers" %}
Track page growth and post performance daily. Export post lifetime performance to identify your top-performing content types (carousel posts, reels, videos, links). Use audience daily snapshots to understand your follower demographics and tailor content accordingly. Combine post and page insights to see which content drives the most engagement relative to reach.
{% endtab %}

{% tab title="Marketing Teams" %}
Monitor campaign performance by exporting page performance insights with custom date ranges. Use Append transformations to combine data from multiple pages (e.g., brand + regional pages) for consolidated reporting. Send data to Looker Studio or BigQuery to build dashboards that track reach, engagement, and audience growth over time.
{% endtab %}

{% tab title="Analysts" %}
Pull detailed post-level metrics and aggregate by content type, creation date, or engagement tier. Use performance insights with daily splits to identify trends and seasonality. Combine Page Insights with Facebook Ads data (via separate data flows) to correlate organic engagement with paid promotion. Export to BigQuery for advanced SQL analysis.
{% endtab %}

{% tab title="AI and Content Strategy" %}
Export post lifetime performance data and send directly to Claude or ChatGPT to generate insights on engagement patterns and content recommendations. Use audience demographics to identify underserved segments. Extract post content along with metrics to analyze sentiment and messaging effectiveness.
{% endtab %}
{% endtabs %}

## Platform-specific notes

* **Reels limitations** — Facebook's API has limited reel metrics support; some engagement data (e.g., detailed reaction breakdowns) may not be available
* **Post creation dates** — Use the "Created after/before" filters to fetch only posts within a specific date range; this helps avoid timeouts on pages with high post volumes
* **Organic vs. paid reach** — Only available in performance insights reports; general overview includes combined reach
* **Video watch time** — Only available for video daily performance reports, not for reels
* **Rate limits** — Large date ranges and high post volumes may cause slow performance; narrow your date range if you encounter delays
* **Permission requirements** — You must have admin or analyst access to the page; business integrations must be authorized in Facebook settings

## Facebook Page Insights common issues

### Connection issues

<details>

<summary>Can't connect to my Facebook page even though I'm the owner</summary>

If you're the page owner but still can't connect, try these steps:

1. **Reconnect your Facebook account** — Go to [Coupler.io connections](https://app.coupler.io/app/connections), remove the Facebook connection, and sign in again.
2. **Check business integrations** — Visit [Facebook Business Settings](https://www.facebook.com/settings/?tab=business_tools) and confirm Coupler.io is listed. Remove and re-authorize it if needed.
3. **Verify admin role** — Go to your page settings and confirm your account has admin access (not just editor or analyst).
4. **Try in a different browser** — Sometimes browser cache issues prevent OAuth from completing; try signing in with a fresh browser session.

If the issue persists after these steps, contact support with your page URL.

</details>

<details>

<summary>Error: "(#100) Object does not exist, cannot be loaded due to missing permission"</summary>

This error means the page couldn't be found or your account doesn't have permission to access it.

**Solutions:**

* Confirm the page is still active and hasn't been deleted or merged
* Verify you have admin or analyst access to the page (check page roles)
* Reconnect your Facebook account using the steps above
* If you're accessing a business page you were added to recently, wait 24 hours for permissions to fully propagate

If you're trying to pull data from a public page you don't own or manage, this isn't supported — you can only access pages where you have an admin or analyst role.

</details>

<details>

<summary>Facebook Insights connector won't connect but Facebook Ads works</summary>

This can happen if the two sources use different permissions.

**Try this:**

1. Remove Coupler.io from your Facebook Business Integrations (settings → business tools)
2. Reconnect your Facebook account from scratch in Coupler.io
3. Grant all requested permissions during the authorization flow

If Facebook Ads works but Page Insights doesn't, it may be due to API changes. Try creating a new data flow and re-selecting your report type and metrics.

</details>

### Missing data

<details>

<summary>Data flow runs but returns no data (empty result)</summary>

This usually happens when the date range or filters don't match your actual data.

**Check these:**

* **Date range** — Verify the start and end dates cover the period when you actually had posts or followers; an old date range may return nothing
* **Page selection** — Confirm you selected the correct page (not an Instagram profile or archived page)
* **Metrics availability** — Some metrics like reels engagement or organic reach may not have data if you didn't publish reels or the metric isn't tracked for your region
* **Historical data limits** — Facebook limits how far back you can pull certain metrics (typically 2 years for lifetime post metrics); very old date ranges may be empty

Run a manual test in the Facebook Insights web UI for the same date range to confirm data exists before troubleshooting further.

</details>

<details>

<summary>Post or video data is missing for a specific date range</summary>

If you're pulling post lifetime or video daily performance and some data is missing:

* **Large post volumes** — If your page has hundreds of posts, the query may time out. Use "Created after/before" filters to split the date range into smaller chunks (e.g., monthly instead of yearly)
* **Unpublished or deleted posts** — Posts that were later unpublished or deleted may not appear in metrics
* **Business page changes** — If the page was recently converted to a business account or had a major restructure, older metrics may not be available

Try running separate data flows for different date ranges and use Append to combine the results.

</details>

<details>

<summary>Specific metrics are blank or showing zeros</summary>

Some metrics may have missing data due to API limitations or inactivity:

* **Reels metrics** — Reel-specific metrics (detailed reaction breakdowns, comment counts) are limited by Facebook's API; some data may be unavailable
* **Organic reach/impressions** — Only available for pages with recent post activity; inactive pages may show zeros
* **Audience demographics** — If few followers fall within certain age ranges or countries, those rows may be empty
* **Video watch time** — Only available for videos published after a certain date; very old videos may not have this metric

This is expected behavior and not a bug. Check the Facebook Insights web UI for the same metric to confirm.

</details>

### Permission errors

<details>

<summary>Error: "User does not have sufficient permissions for this action on this page"</summary>

This means your account doesn't have the required role on the page.

**To fix:**

1. Ask a page admin to visit **Page Settings → Roles and Permissions** and assign you an **Admin** or **Analyst** role (not just Editor)
2. Reconnect your Facebook account in Coupler.io after the role is updated
3. If you are the page owner, try removing Coupler.io from your [Facebook Business Integrations](https://www.facebook.com/settings/?tab=business_tools) and re-authorizing from scratch

Editor and Moderator roles don't have permission to access Page Insights API data.

</details>

<details>

<summary>Business integration shows as removed or unauthorized</summary>

If Coupler.io disappears from your authorized integrations:

1. Go to [Facebook Business Settings](https://www.facebook.com/settings/?tab=business_tools)
2. Look for "Coupler" or "Coupler.io" under authorized apps
3. If it's not there, remove your Facebook connection in Coupler.io and reconnect from scratch
4. When you reconnect, make sure you grant all requested permissions

Facebook occasionally resets business integrations for security reasons; reconnecting usually fixes this.

</details>

### Data discrepancies

<details>

<summary>Numbers in Coupler don't match Facebook Insights web UI</summary>

Small discrepancies (1-5%) are normal due to:

* **Reporting delays** — Facebook updates metrics with a slight delay; pulling data at different times may show slightly different numbers
* **Time zone differences** — Ensure your Coupler.io data flow and Facebook Insights UI are using the same time zone
* **Metric definitions** — Some metrics in the API have slightly different definitions than the web UI (e.g., "reach" vs. "unique reach")

Larger discrepancies (>10%) may indicate a filtering or grouping issue. Check that your date range, page selection, and dimensions (if any) match between the two sources.

</details>

<details>

<summary>Post metrics don't match when pulled at different times</summary>

Post lifetime metrics can fluctuate slightly as Facebook updates engagement data retroactively.

* **Recent posts** — Metrics for posts less than 24 hours old may change as engagement continues
* **Delayed updates** — Facebook can take up to 48 hours to fully process and finalize metrics
* **Re-shared posts** — Metrics may update if a post is re-shared or boosted with ads

For reporting, pull post data 24-48 hours after publishing to get more stable numbers.

</details>

### Rate limits

<details>

<summary>Data flow times out or fails with high post volume</summary>

Large queries can hit timeout limits when pulling data from pages with thousands of posts.

**Solutions:**

1. **Use date range filters** — Instead of pulling all-time data, set a specific start/end date (e.g., last 90 days)
2. **Split by period** — Use the "Split data by period" option (Daily or Monthly) to break the query into smaller chunks
3. **Use creation date filters** — For post reports, set "Created after" and "Created before" to narrow the dataset
4. **Run multiple data flows** — Create separate data flows for different date ranges and append the results

Example: Instead of one data flow for 2 years of data, create 4 data flows covering Jan-Mar, Apr-Jun, Jul-Sep, Oct-Dec, then Append them together.

</details>

<details>

<summary>"Service temporarily unavailable" error</summary>

This error means Facebook's API is temporarily down or rate-limited.

**What to do:**

1. Wait 5-10 minutes and try running the data flow again
2. If it persists, check [Facebook's API status page](https://developers.facebook.com/status) for any ongoing incidents
3. If your account is hitting rate limits, reduce the date range or frequency of data flow runs
4. Contact support if the error continues for more than an hour

This is usually temporary and resolves on its own.

</details>

## Facebook Page Insights FAQ

<details>

<summary>Can I pull data from a public Facebook page I don't own or manage?</summary>

No. Facebook's API only allows you to access pages where you have an admin or analyst role. You cannot pull data from public pages you don't manage, even if you follow them. Contact the page owner and ask them to give you admin or analyst access if you need their data.

</details>

<details>

<summary>What's the difference between "Page: general overview" and "Page: performance insights"?</summary>

General overview includes all basic page metrics (followers, impressions, reach, engagement, clicks) but doesn't let you filter by content type or breakdown. Performance insights lets you view the same metrics broken down by post type (link, photo, video, etc.) and choose specific metrics to include. Use performance insights if you want to see which content types perform best.

</details>

<details>

<summary>Can I get individual post comments and shares data?</summary>

Not directly through Coupler.io. The Facebook Page Insights API provides aggregate engagement metrics (total reactions, engagement count) but not individual comment text or detailed share data. Post lifetime performance does include engagement metrics like reactions and total engagement, but not comment-by-comment breakdowns. If you need comment text analysis, you'd need to export manually from Facebook and process it separately, or ask support about feature requests.

</details>

<details>

<summary>Why are my reel metrics incomplete or blank?</summary>

Facebook's API has limitations on reel metrics. Detailed reaction breakdowns, comment counts, and some other metrics are not available through the API. You can pull reel views and general engagement, but expect some data points to be unavailable. Check the [Facebook Insights limitations documentation](https://developers.facebook.com/docs/graph-api/reference/insights) for the latest supported metrics.

</details>

<details>

<summary>Can I export demographic data (age, gender, location) for my followers?</summary>

Yes. Use the "Page: audience daily snapshot" report type. This gives you follower counts broken down by age range, gender, country, and city for each day. Note that small numbers (<5 followers) may be aggregated for privacy reasons.

</details>

<details>

<summary>How do I combine data from multiple Facebook pages into one table?</summary>

Create a separate data flow for each page with the same report type and metrics. Once both complete successfully, use the Append transformation to combine them into one table. Each row will include a page name or identifier so you can see which data came from which page.

</details>

<details>

<summary>Can I compare my Facebook data with Instagram data?</summary>

Yes, but they're separate sources in Coupler.io. Create a Facebook data flow and a separate Instagram Insights data flow, then use Join or Append transformations to combine them. Note that metrics have different names and definitions between platforms, so you may need to do some mapping in your destination.

</details>

<details>

<summary>Why does the date range matter for post data, and what's the difference between date range and creation date filters?</summary>

**Date range** (start/end date) — Filters by the reporting period. Useful for page metrics and video daily performance.

**Creation date filters** ("Created after/before") — Filters by when posts were published. Use this for post lifetime and reel performance reports when you want to see only posts from a specific time period. This is more efficient and avoids timeouts on pages with high post volume.

For post reports, creation date filters are preferred.

</details>

<details>

<summary>How often should I schedule my data flow to run?</summary>

It depends on your report type:

* **Page overview/performance** — Daily is ideal; run in the morning to get the previous day's data
* **Post lifetime performance** — Daily or every 2 days; metrics are finalized 24-48 hours after posting
* **Audience daily snapshot** — Daily; captures the previous day's follower demographics
* **Video daily performance** — Daily

Don't run more frequently than daily unless you need real-time updates. Facebook metrics aren't updated in real-time, so hourly runs will just pull the same data multiple times.

{% hint style="info" %}
See the [Best Practices](https://docs.coupler.io/sources/category/social-media/facebook-page-insights/best-practices.md) section for scheduling recommendations.
{% endhint %}

</details>

<details>

<summary>What if my data flow is disabled due to errors?</summary>

A data flow gets disabled after repeated failures. Don't panic — this usually means a metric was deprecated or permissions changed.

**Steps to fix:**

1. Go to [Coupler.io connections](https://app.coupler.io/app/connections) and reconnect your Facebook account
2. Edit your data flow and re-select your metrics (outdated metrics may have been removed from the API)
3. Run a manual test
4. Once it passes, re-enable scheduling

If the error persists, contact support with the error message.

{% hint style="info" %}
Check [Common Issues](#facebook-page-insights-common-issues) for specific error messages and solutions.
{% endhint %}

</details>

<details>

<summary>Can I use macros (like {{today}} or {{30daysago}}) in my date fields?</summary>

Yes, date fields support macros. Instead of manually setting dates, you can use:

* `{{today}}` for the current date
* `{{30daysago}}` to pull the last 30 days
* `{{yesterday}}` for the previous day

This is especially useful for scheduled data flows so the date range automatically updates. [Learn more about macros](https://docs.coupler.io/functionality/macros-in-data-flows).

</details>

<details>

<summary>How do I send Facebook data to Claude or ChatGPT for analysis?</summary>

When creating your data flow, choose "Claude", "ChatGPT", or another AI destination instead of Google Sheets. Coupler.io will send your data directly to the AI tool, and you can set a prompt to analyze it (e.g., "Summarize the top 5 performing posts and explain why they succeeded"). The AI will generate insights based on your data.

AI destinations work best with post or engagement data where you have specific metrics to analyze.

</details>

<details>

<summary>What permissions does Coupler.io need from Facebook?</summary>

Coupler.io requests:

* **pages\_read\_engagement** — To read page metrics and engagement data
* **pages\_read\_user\_content** — To access page posts and content metrics
* **read\_insights** — To access Page Insights data

You must grant all permissions during the authorization flow. If you denied permissions initially, reconnect your account and ensure you click "Allow" for all requests.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/social-media/facebook-page-insights.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
