A scheduled Meta Graph API pipeline is the most reliable way to export Facebook Page Insights to BigQuery. For 1 Page, a Python job can call the Meta Page Insights endpoint and write rows directly to BigQuery. For multiple Pages or recurring reporting, use Cloud Storage as a staging layer, then load newline-delimited JSON into BigQuery.
The workflow is:
Meta Graph API -> extraction script -> Cloud Storage or BigQuery -> reporting tables
Meta does not offer a universal one-click export for this workflow. An API-based pipeline gives you control over the metrics you request, historical backfills, schema design and duplicate handling.
| Layer | Recommended tool | Purpose |
|---|---|---|
| Source | Meta Graph API | Retrieves Facebook Page Insights |
| Authentication | Meta Page access token | Authorizes Page data access |
| Extraction | Python on Cloud Run, Cloud Functions or a scheduler | Calls the API and normalizes responses |
| Staging | Cloud Storage, optional | Stores raw newline-delimited JSON |
| Warehouse | BigQuery | Stores queryable historical data |
| Transformation | BigQuery SQL or scheduled queries | Deduplicates and creates reporting tables |
Meta Page Insights requires a Page access token and the required permissions, including read_insights and pages_read_engagement. The requesting person must also have the ANALYZE task for the Page.
Facebook Page Insights provides metrics about Page performance and audience activity. The available metrics depend on the API version and object type, so check Meta's current Page Insights reference before adding metrics to a production pipeline. Some metrics have been deprecated or are scheduled for deprecation.
Typical metrics include:
Keep Page-level and post-level data in separate tables. Page Insights describe the Page over a reporting period. Post insights describe an individual piece of content.
Prepare:
Meta's Graph API uses an endpoint in this form:
/{page-id}/insights/{metric-name}
The API supports time filters such as since and until. The until value is non-inclusive, so define the requested interval carefully in the extraction logic. Meta also applies historical retention and request-window limits to Page Insights.
A raw table should preserve both the normalized numeric value and the original API value. Some metrics return structured objects rather than a single number, so keeping the original value prevents information loss.
CREATE TABLE `PROJECT_ID.facebook_raw.page_insights` (
page_id STRING NOT NULL,
metric STRING NOT NULL,
period STRING,
end_time TIMESTAMP,
metric_value FLOAT64,
value_json STRING,
fetched_at TIMESTAMP NOT NULL
)
PARTITION BY DATE(end_time)
CLUSTER BY page_id, metric;
The value_json column retains demographic or breakdown values without forcing every metric into the same numeric format.
Install the required libraries:
pip install requests google-cloud-bigquery
Set these environment variables:
export META_ACCESS_TOKEN="your-page-access-token"
export META_PAGE_ID="your-page-id"
export META_API_VERSION="your-supported-api-version"
export GCP_PROJECT_ID="your-google-cloud-project"
export BIGQUERY_TABLE="your-project.facebook_raw.page_insights"
export META_SINCE="unix-timestamp"
export META_UNTIL="unix-timestamp"
export META_PERIOD="supported-period"
This script retrieves each metric and inserts normalized rows into BigQuery:
import json
import os
from datetime import datetime, timezone
import requests
from google.cloud import bigquery
META_ACCESS_TOKEN = os.environ["META_ACCESS_TOKEN"]
META_PAGE_ID = os.environ["META_PAGE_ID"]
META_API_VERSION = os.environ["META_API_VERSION"]
META_SINCE = os.environ["META_SINCE"]
META_UNTIL = os.environ["META_UNTIL"]
META_PERIOD = os.environ["META_PERIOD"]
BIGQUERY_TABLE = os.environ["BIGQUERY_TABLE"]
METRICS = [
"page_impressions_unique",
"page_views_total",
]
def fetch_metric(metric_name):
url = (
f"https://graph.facebook.com/{META_API_VERSION}/{META_PAGE_ID}/insights/{metric_name}"
)
params = {
"access_token": META_ACCESS_TOKEN,
"since": META_SINCE,
"until": META_UNTIL,
"period": META_PERIOD,
}
response = requests.get(url, params=params, timeout=60)
response.raise_for_status()
payload = response.json()
if "error" in payload:
raise RuntimeError(payload["error"])
return payload.get("data", [])
def normalize_rows():
fetched_at = datetime.now(timezone.utc).isoformat()
rows = []
for metric_name in METRICS:
metric_series = fetch_metric(metric_name)
for series in metric_series:
metric = series.get("name", metric_name)
period = series.get("period")
for item in series.get("values", []):
raw_value = item.get("value")
numeric_value = None
if isinstance(raw_value, (int, float)):
numeric_value = float(raw_value)
rows.append(
{
"page_id": META_PAGE_ID,
"metric": metric,
"period": period,
"end_time": item.get("end_time"),
"metric_value": numeric_value,
"value_json": json.dumps(raw_value),
"fetched_at": fetched_at,
}
)
return rows
def load_to_bigquery(rows):
client = bigquery.Client()
errors = client.insert_rows_json(
BIGQUERY_TABLE,
rows,
)
if errors:
raise RuntimeError(f"BigQuery insert errors: {errors}")
if __name__ == "__main__":
rows = normalize_rows()
if rows:
load_to_bigquery(rows)
print(f"Inserted {len(rows)} rows into {BIGQUERY_TABLE}")
else:
print("No Page Insights rows returned")
Meta returns metric series with values and reporting periods. The script keeps numeric values in metric_value and stores the original API value in value_json.
A repeated extraction for the same interval can create duplicate records when the job writes directly to BigQuery. Use Page ID, metric, period and metric timestamp as the deduplication key.
Create a reporting table with this query:
CREATE OR REPLACE TABLE `PROJECT_ID.facebook_reporting.page_insights_clean` AS
SELECT
page_id,
metric,
period,
end_time,
metric_value,
value_json,
fetched_at
FROM `PROJECT_ID.facebook_raw.page_insights`
QUALIFY ROW_NUMBER() OVER (
PARTITION BY page_id, metric, period, end_time
ORDER BY fetched_at DESC
) = 1;
For larger pipelines, write API results to a staging table first, then use MERGE to update the reporting table. This makes retries and backfills safer than appending directly to the final table.
Use Cloud Storage as a staging layer when you need:
Write one newline-delimited JSON object per row:
{"page_id":"123","metric":"page_views_total","period":"x","end_time":"timestamp","metric_value":42,"value_json":"42","fetched_at":"timestamp"}
Then load the file into BigQuery:
bq load \
--source_format=NEWLINE_DELIMITED_JSON \
--autodetect \
PROJECT_ID:facebook_raw.page_insights \
gs://BUCKET_NAME/facebook/page_insights/file.json
BigQuery supports newline-delimited JSON loads from Cloud Storage. Cloud Storage paths can also use wildcards when the files share a compatible schema.
For recurring Cloud Storage transfers, create the destination table and schema in advance. The BigQuery Data Transfer Service can append new files or mirror the destination table, but files in recurring transfers must keep a compatible schema.
This setup works well for a recurring production pipeline:
Cloud Functions works for a lightweight single-Page extraction. Use a scheduled trigger and keep the function focused on retrieving data from Meta and loading it into BigQuery.
BigQuery scheduled queries are useful for transforming raw rows into clean reporting tables. They do not replace the Meta API extraction step.
CREATE OR REPLACE TABLE `PROJECT_ID.facebook_reporting.page_insights_latest` AS
SELECT
page_id,
metric,
period,
end_time,
metric_value,
value_json
FROM `PROJECT_ID.facebook_raw.page_insights`
QUALIFY ROW_NUMBER() OVER (
PARTITION BY page_id, metric, period, end_time
ORDER BY fetched_at DESC
) = 1;
BigQuery scheduled queries can run recurring GoogleSQL transformations. Scheduled INSERT operations need separate duplicate handling when a job is retried or runs more than once.
After the clean table exists, calculate reporting metrics with SQL:
SELECT
DATE(end_time) AS reporting_date,
metric,
SUM(metric_value) AS metric_value
FROM `PROJECT_ID.facebook_reporting.page_insights_latest`
WHERE page_id = "YOUR_PAGE_ID"
GROUP BY reporting_date, metric
ORDER BY reporting_date, metric;
To compare multiple Pages:
SELECT
page_id,
metric,
SUM(metric_value) AS total_value
FROM `PROJECT_ID.facebook_reporting.page_insights_latest`
WHERE metric IN (
"page_impressions_unique",
"page_views_total"
)
GROUP BY page_id, metric
ORDER BY page_id, metric;
For dashboarding, connect BigQuery to Looker Studio, Looker, Tableau or Power BI. Keep the raw API table separate from dashboard-ready tables so metric changes do not overwrite the original extraction.
Meta changes the Page Insights metric catalogue. An API error for an invalid metric usually means that the metric is unsupported, deprecated or unavailable for the Page or API version. Check each metric before adding it to the scheduled job.
Most Page Insights metrics update periodically rather than continuously. A successful API response does not mean that the value represents the latest activity.
Meta does not provide unlimited historical Page Insights through the endpoint. Start exporting before you need long-term trend analysis, and retain the BigQuery data separately from Meta's API retention window.
Audience breakdowns may be unavailable when the underlying audience is too small. Treat a missing demographic value as unavailable data, not as zero.
Do not place a Page access token in browser JavaScript, Git repositories, public notebooks or BigQuery rows. Store the token in Secret Manager and allow only the extraction service account to retrieve it.
Use direct Python-to-BigQuery inserts for a small internal workflow with 1 or a few Pages.
Use Meta API -> Cloud Storage -> BigQuery staging -> deduplicated reporting table when the data supports recurring client reports, multiple Pages, historical backfills or audit requirements.
In both cases, keep the Page ID, metric name, insight timestamp, original metric value and fetch timestamp on every row. Partition by the insight timestamp and deduplicate before reporting. This keeps Facebook Page Insights queryable when Meta changes its available metrics or API responses.