Circle Separator7 mins read

How to Export Facebook Page Insights to BigQuery

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.

LayerRecommended toolPurpose
SourceMeta Graph APIRetrieves Facebook Page Insights
AuthenticationMeta Page access tokenAuthorizes Page data access
ExtractionPython on Cloud Run, Cloud Functions or a schedulerCalls the API and normalizes responses
StagingCloud Storage, optionalStores raw newline-delimited JSON
WarehouseBigQueryStores queryable historical data
TransformationBigQuery SQL or scheduled queriesDeduplicates 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.

What Data Can You Export?

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:

  • Page impressions
  • Unique Page impressions
  • Page views
  • Page fans
  • Engagement metrics
  • Video performance
  • Page post insights
  • Demographic breakdowns, where available

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.

What You Need Before Starting

Prepare:

  1. A Meta developer account
  2. A Meta app
  3. A Facebook Page that you own or manage
  4. A Page access token
  5. The Page ID
  6. The required Meta permissions
  7. A Google Cloud project
  8. A BigQuery dataset
  9. A service account with permission to write to BigQuery

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.

Create a BigQuery Table

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.

Python Script to Export Page Insights

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.

Avoid Duplicate Rows When the Job Runs Repeatedly

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 for a Production Pipeline

Use Cloud Storage as a staging layer when you need:

  • Multiple Facebook Pages
  • Raw API response retention
  • Replayable loads
  • Backfills
  • Separate extraction and warehouse jobs
  • Schema validation before ingestion

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.

Schedule the Export

Cloud Scheduler and Cloud Run

This setup works well for a recurring production pipeline:

  1. Deploy the Python extractor to Cloud Run.
  2. Store the Meta access token in Secret Manager.
  3. Give the Cloud Run service account permission to write to BigQuery.
  4. Create a Cloud Scheduler job that calls the Cloud Run endpoint.
  5. Send logs and API errors to Cloud Logging.

Cloud Functions

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

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.

Query Facebook Page Insights in BigQuery

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.

Important Limitations

Some Metrics May No Longer Be Available

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.

Page Insights Are Not Real-Time Data

Most Page Insights metrics update periodically rather than continuously. A successful API response does not mean that the value represents the latest activity.

Historical Data Is Limited

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.

Demographic Results May Be Suppressed

Audience breakdowns may be unavailable when the underlying audience is too small. Treat a missing demographic value as unavailable data, not as zero.

Access Tokens Must Be Protected

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.

Choose the Right Pipeline

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.

Next Read