> 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/best-practices.md).

# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Use separate data flows by report type</strong></td><td>Create one data flow for page metrics, another for post performance, and another for audience demographics. This keeps your data organized and makes it easier to troubleshoot if one fails.</td></tr><tr><td><strong>Filter by date range to avoid timeouts</strong></td><td>For pages with high post volume, always set a specific start/end date instead of pulling all historical data at once. Pull monthly or quarterly data in separate flows and append them together.</td></tr><tr><td><strong>Use the "Split data by period" option</strong></td><td>When pulling page performance insights, enable daily or monthly splits to get granular trends without hitting API limits. Monthly splits are usually faster than daily.</td></tr><tr><td><strong>Send post data to AI for analysis</strong></td><td>Export post lifetime performance directly to Claude or ChatGPT to generate insights on top-performing content themes and engagement patterns without manual analysis.</td></tr></tbody></table>

## Data refresh and scheduling

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Wait 24-48 hours before pulling post metrics</strong></td><td>Post engagement metrics can fluctuate in the first 24 hours and aren't fully finalized until 48 hours after publication. Schedule post lifetime performance pulls to run daily or every 2 days, not hourly.</td></tr><tr><td><strong>Run page metrics daily</strong></td><td>Follower and reach metrics are typically finalized by the next day. Schedule page overview and performance insights to run every morning to get the previous day's data.</td></tr><tr><td><strong>Combine multiple pages with Append</strong></td><td>If you manage multiple Facebook pages, create a single data flow per page, run them all, then use the Append transformation to combine results into one table. This is faster and cleaner than creating a complex multi-page query.</td></tr></tbody></table>

## Performance optimization

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Limit metrics to what you actually need</strong></td><td>Pulling fewer metrics slightly speeds up queries. Only select metrics you plan to use or analyze. Avoid selecting all available metrics if you only need 3-4.</td></tr><tr><td><strong>Use post creation date filters instead of time ranges</strong></td><td>For post lifetime and reel performance reports, the "Created after/before" filters are more efficient than date ranges. They directly filter posts instead of pulling all posts and filtering later.</td></tr></tbody></table>

## Common pitfalls

{% columns %}
{% column %}
**Do**

* Verify page access in Facebook before setting up a data flow
* Run a manual test before scheduling to catch permission or data issues early
* Use narrow date ranges for high-volume pages (100+ posts per month)
* Check Facebook Insights web UI to confirm data exists before troubleshooting
* Split very large historical pulls into multiple smaller data flows
  {% endcolumn %}

{% column %}
**Don't**

* Try to pull all-time data from a page with thousands of posts in one query
* Expect real-time data; schedule pulls after 24 hours for post metrics
* Use Editor or Moderator roles; ensure you have Admin or Analyst access
* Re-run failed data flows immediately; wait a few minutes for Facebook API to recover
* Pull metrics for reels expecting full engagement breakdowns; API limitations mean some data isn't available
  {% endcolumn %}
  {% endcolumns %}

{% hint style="danger" %}
**Critical:** If a data flow is disabled due to repeated failures, don't immediately re-run it. Check the error message first — it's often due to deprecated metrics or permission changes. Try reconnecting your Facebook account and re-selecting your metrics before running again. Repeated quick retries can trigger Facebook's rate limits.
{% endhint %}


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.