Advanced Analytica Advanced Analytica: IBOM
← All connectors
Facebook Pages logo

Source connector

Facebook Pages

Set up Facebook Pages as a source and move its data into your chosen destination.

Version 3.3.0 community beta

Facebook Pages

Set up the Facebook Pages source connector and find its reference information on this page.

Prerequisites

You need a Facebook app, a long-lived Page access token and the Page ID you want to sync.

:::note This connector calls v26.0 of the Facebook Graph API. :::

Meta only returns Page Insights data for Pages with at least 100 likes. The connector checks your connection by reading the page_insights stream. An empty response still passes. You can therefore set up a Page with fewer than 100 likes and sync non-insights streams, including page and post. Its insights streams return no records until the Page reaches 100 likes.

Setup guide

Step 1: Set up Facebook Pages

  1. Create a Facebook Developer Account. Follow these instructions to create one.
  2. Create a Facebook App. Choose “Company” as the app’s purpose. Complete the remaining fields, create your app and follow the “Connect a User Page” section.
  3. Connect a User Page using the Graph API Explorer. Choose your app in the Meta App field. Choose your Page in the User or Page field. Add these permissions:
    • pages_read_engagement
    • pages_read_user_content
    • pages_show_list
    • read_insights
  4. Click Generate Access Token and follow the instructions.

After completing these steps, your setup should look similar to this:

  1. Generate Long-Lived User Access Token.
  2. Generate Long-Lived Page Token.

Step 2: Set up the connector in Airbyte

  1. Click Sources in the left navigation bar. Click + New source in the top-right corner.
  2. Select Facebook Pages and enter a source name.
  3. For Page Access Token, enter the long-lived Page token you generated in Step 1. You can also use a long-lived User token. That user must be able to generate a Page token for the configured Page.
  4. For Page ID, enter the Page’s ID or username. If the Page URL is https://www.facebook.com/Test-1111111111, use Test-1111111111.
  5. (Optional) Set Page Size to control the records requested per API call for each paginated stream. These streams are post, post_insights, video_insights, reel_insights, comment and rating. The default is 100, and valid values range from 1 to 100. Reduce it if you see “Please reduce the amount of data you’re asking for” errors.
  6. (Optional) Set Page Insights Metrics, Post Insights Metrics, Video Insights Metrics or Reel Insights Metrics to choose the metrics requested by each insights stream. See Insights metrics and period.
  7. (Optional) Set Page Insights Period to request one aggregation period, such as day, for the page_insights stream. Valid values are day, week, days_28, month, lifetime and total_over_range.
  8. (Optional) Set Start Date to the earliest date read by the page_insights stream. Use the YYYY-MM-DDTHH:MM:SSZ format, for example 2024-01-01T00:00:00Z. Meta retains about two years of Page Insights history. See Supported sync modes.
  9. Click Set up source.

Create your own OAuth App

Follow Facebook documentation to create an OAuth App.

Your OAuth App needs these permissions to sync data through the Facebook Pages source connector:

  • pages_read_engagement
  • pages_read_user_content
  • pages_show_list
  • read_insights

If specific Page fields return permission errors, see Meta’s Permissions Reference for other permissions you might need. Request the fewest permissions required for normal operation.

Supported sync modes

The Facebook Pages source connector supports these sync modes:

The post stream uses full refresh by default. In Incremental mode, the connector saves the newest created_time it has seen. During the next sync, it asks Facebook only for posts created after that point. This reduces the data read during every sync after the first. The first incremental sync reads the complete post history. A full refresh always reads the complete history. The filter uses each post’s creation time. Therefore, incremental mode doesn’t refresh later edits, reactions or comment counts for previously synced posts. Use full refresh when you need that data to remain current.

The page_insights stream uses full refresh by default, requesting only Facebook’s default trailing window. In Incremental mode, the connector saves the newest end_time it has seen. During the next sync, it asks Facebook only for subsequent days. Set Start Date to backfill history. The connector reads 90-day windows because Facebook returns at most 90 days per request. Facebook retains about two years of history. Start Date applies in both modes. A full refresh with this setting also reads 90-day windows from that date. Facebook’s newest point usually belongs to a day still in progress. Each incremental sync therefore rereads the two days before the saved end_time. You can expect those days to reappear in your destination. Each record represents one metric and period for one window. If your destination deduplicates by primary key, use Incremental - Append instead of a deduplicated mode. Otherwise, windows overwrite each other. If you leave Start Date empty, the first incremental sync reads Facebook’s default window. Later syncs continue from that point. A connection paused for over 90 days might need a reset or a Start Date before catching up.

Supported streams

Version 3.1.0 added the video_insights, reel_insights, comment and rating streams. They need permissions that older tokens might lack. Facebook might reject their requests with error code 10 or a code from 200 to 299. It might instead return a message mentioning a permission. The connector logs the error and skips the request instead of failing the sync. These streams can therefore sync zero records without an error. If one is empty, confirm your token has the permissions listed in Step 1.

StreamGraph API endpointNotes
page/{page-id}One record describing the Page. Airbyte requests only the fields you select in the connection’s Schema tab.
post/{page-id}/feedOne record per post. Paginated, so Page Size applies. Airbyte requests only the fields you select. Supports incremental sync on created_time.
page_insights/{page-id}/insightsOne record per metric and period, not per day. Metrics and period are configurable. Supports incremental sync on end_time, with Start Date to backfill.
post_insights/{page-id}/feed with an insights.metric(...) field selectionPost-level insights, one record per metric and period. Paginated, so Page Size applies. Metrics are configurable.
video_insights/{page-id}/videos with a video_insights.metric(...) field selectionLifetime video insights per Page video, one record per metric. Paginated, so Page Size applies. Metrics are configurable.
reel_insights/{page-id}/video_reels with a video_insights.metric(...) field selectionLifetime Reels insights per Page reel, such as blue_reels_play_count, one record per metric. Paginated, so Page Size applies. Metrics are configurable.
comment/{post-id}/comments for each post in /{page-id}/feedOne record per comment, including replies, with the parent post_id added. This makes one request per post, so a Page with many posts uses many API calls. Needs pages_read_user_content.
rating/{page-id}/ratingsOne record per recommendation or review. Recommendations have no ID of their own, so this stream has no primary key. Needs pages_read_user_content.

Insights metrics and period

Choose the metrics requested by each insights stream using Page Insights Metrics, Post Insights Metrics, Video Insights Metrics and Reel Insights Metrics. If you leave a setting empty, the connector requests these defaults:

  • page_insights: page_total_actions, page_post_engagements, page_fan_adds_by_paid_non_paid_unique, page_media_view, page_total_media_view_unique
  • post_insights: post_media_view, post_total_media_view_unique, post_clicks, post_clicks_by_type, post_reactions_by_type_total
  • video_insights: total_video_views, total_video_complete_views, total_video_avg_time_watched, total_video_view_total_time, total_video_reactions_by_type_total
  • reel_insights: blue_reels_play_count, fb_reels_total_plays, fb_reels_replay_count, post_video_avg_time_watched, post_video_view_time, post_video_likes_by_reaction_type, post_video_social_actions

By default, Facebook returns every supported period for each page_insights metric. These are usually day, week and days_28, producing about three records per metric and request. If you need only one, set Page Insights Period to that period. The stream then requests only that period.

A setting replaces the defaults instead of extending them, so include every metric you need. Facebook rejects the entire request if any metric is misspelt or deprecated. After changing a setting, check that list first if a sync returns the “must be a valid insights metric” error. Each additional metric also increases the response size and your Graph API usage.

All insights streams follow Meta’s Page Insights limits. Data is available only for Pages with at least 100 likes. Most metrics refresh every 24 hours, and Meta retains at most two years of history.

Reference

This connector uses the Meta Graph API with the https://graph.facebook.com/v26.0 endpoint. Airbyte requests the selected Page and Post fields from the connector catalogue. It also requests your configured insights metrics, or the defaults listed in Insights metrics and period.

Use these parameter names for programmatic configuration:

FieldRequiredDescription
access_tokenYesLong-lived Page access token for the Facebook Page. The connector also accepts a long-lived User access token that can generate a Page access token for the configured Page.
page_idYesFacebook Page ID.
page_sizeNoNumber of records to request per page for the paginated streams: post, post_insights, video_insights, reel_insights, comment, and rating. Defaults to 100. Valid values are 1 through 100.
page_insights_metricsNoArray of metrics for the page_insights stream. Replaces the defaults.
post_insights_metricsNoArray of metrics for the post_insights stream. Replaces the defaults.
video_insights_metricsNoArray of lifetime metrics for the video_insights stream. Replaces the defaults.
reel_insights_metricsNoArray of lifetime metrics for the reel_insights stream. Replaces the defaults.
page_insights_periodNoAggregation period for the page_insights stream: day, week, days_28, month, lifetime, or total_over_range. If empty, Facebook returns every period it supports.
start_dateNoEarliest date for the page_insights stream, in the format YYYY-MM-DDTHH:MM:SSZ. If empty, Facebook’s default window is used.

Limitations and troubleshooting

”This application has not been approved to use this API”

This error means Meta rejected the API request. The app that generated the token lacks approval for the requested API, permission or Page field.

Use a token from an app with the permissions required by the streams you sync:

  • pages_read_engagement
  • pages_read_user_content
  • pages_show_list
  • read_insights

Your own Meta app might need App Review and Advanced Access to use these permissions in production. The person generating the token must also be able to perform the required Page task. For Page Insights, Meta requires access to a Page you own or administer. Alternatively, you must be able to perform the ANALYZE task on it.

”Error while generating page access token”

Before reading any stream, the connector exchanges your configured token for a Page access token by calling /{page-id}?fields=access_token. If Meta rejects the call, the check or sync fails. It returns Error while generating page access token: followed by Meta’s response.

Resolve this error as follows:

  • Confirm that Page ID is the ID or username of the Page belonging to the token. A Page access token can generate a token only for its own Page.
  • Confirm the user who generated the token can still perform a Page task. Also check that the token hasn’t expired or become invalid, such as after a password change. Generate a new long-lived token if needed.

”Please reduce the amount of data you’re asking for”

The Graph API returns this error when a response is too large to build in time. It uses error code 1, often with HTTP 500. Meta returns it intermittently, so the connector retries the request with backoff. If all retries fail, the sync returns a transient error. It usually succeeds on a later attempt. Version 2.1.3 failed immediately with a configuration error instead of retrying. Upgrade to 2.1.4 or later to restore retries.

If the error continues, reduce each response’s size:

  • Deselect fields in the Schema tab. Open the connection’s Schema tab and deselect unnecessary fields for the affected stream. The connector requests only selected fields. This applies to the page and post streams.
  • Reduce the page size. Set Page Size in the source settings to a lower value, such as 25 or 50. This applies to the post, post_insights, video_insights, reel_insights, comment and rating streams.

page failures for New Pages Experience Pages

Meta deprecated the legacy Page fields current_location, genre, network, parking and start_info for New Pages Experience Pages. Requesting these fields returns an error on Graph API v26.0 and later. The connector calls v26.0 from version 3.3.0. Meta plans to extend the deprecation to every API version. Meta also doesn’t provide the live_videos edge for New Pages Experience Pages.

Before version 3.0.0, the connector requests these fields. The entire page stream therefore fails for a New Pages Experience Page. The sync returns either the Request contains invalid/deprecated field. error or the Facebook API request contains invalid Page fields, metrics, or permissions error. A Facebook message beginning with (#10) To use live-video-api follows the error. Upgrade to version 3.0.0 or later, which no longer requests these fields. Then refresh the source schema and update downstream models referencing the removed columns. See migration guide for the complete list of removed columns.

”Facebook API request contains invalid Page fields, metrics, or permissions”

From version 2.1.3, the connector returns this configuration error for non-retryable HTTP 400 responses from the Graph API. It includes Facebook’s error message, showing what Facebook rejected. Earlier versions retried these requests several times before failing, which hid Facebook’s message.

Read the Facebook message following the error. It usually identifies an unsupported Page or Post field, or one your token can’t read. Deselect that field in the connection’s Schema tab. Alternatively, use a token with the required permissions.

Missing reach metrics in Page Insights and Post Insights

Meta retired the page_impressions_*_unique and post_impressions_*_unique metrics. The Graph API rejects an entire Insights request when any requested metric is invalid. Requesting these metrics therefore returned (#100) The value must be a valid insights metric and broke both insights streams. It also broke source setup because the connection check queries page_insights. See Meta’s deprecated metrics list.

From version 2.1.2, the connector no longer requests these metrics. Only total reach has a replacement. The paid, viral, non-viral, fan and organic reach breakdowns have no equivalent. They are permanently unavailable from the API.

StreamNo longer emittedReplacement
page_insightspage_impressions_uniquepage_total_media_view_unique
page_insightspage_impressions_paid_unique, page_impressions_viral_unique, page_impressions_nonviral_uniquenone
post_insightspost_impressions_uniquepost_total_media_view_unique
post_insightspost_impressions_paid_unique, post_impressions_fan_unique, post_impressions_organic_unique, post_impressions_viral_unique, post_impressions_nonviral_uniquenone

The stream schemas remain unchanged, so you don’t need to refresh the schema. Rows for the removed metrics simply stop arriving. Clear the affected streams if you want consistent history in your destination.

Product catalogs field unavailable

From version 2.0.4, the Page stream no longer syncs the product_catalogs field. It will always be null. The Facebook Graph API returns only product catalogues owned directly by the Page, not those owned by a Business. Most product catalogues are now Business-owned because Page-owned catalogues are a legacy feature. This connector also uses Page access tokens. Therefore, the product_catalogs field wouldn’t return meaningful data for most users.

Data type map

Integration TypeAirbyte TypeNotes
stringstring
numbernumber
arrayarray
objectobject

Performance considerations

By default, Facebook heavily throttles API tokens generated from Facebook Apps. These tokens make Airbyte syncs impractical. Rate limiting can make your syncs take days. Follow the Setup Guide above to generate a Long-Lived Page Token.

From version 3.0.2, the connector exchanges your token for a Page access token once per sync. Previously, it exchanged the token before every Graph API request. This change reduces API calls.

When Meta throttles a request, the X-Business-Use-Case-Usage response header states when access will return. The connector waits for that period, up to 10 minutes, before retrying. It doesn’t retry on a fixed schedule. Each additional stream and metric increases usage. The comment stream makes one request per post.

The Graph API can report rate limits through HTTP 400. Error codes include 4, 17, 32, 613 and 80001. From version 2.1.3, the connector recognises these codes and any error Meta marks as transient. It retries those requests with backoff instead of failing immediately. Retries are limited. If throttling continues until retries run out, the sync still fails with a transient error. It succeeds on a later attempt after the quota resets.

See Facebook’s documentation on rate limiting for the complete code list and guidance on requesting a quota upgrade.

IP allow list

If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Changelog

Expand to review
VersionDatePull RequestSubject
3.3.02026-11-1090129Move from Graph API v24.0 to v26.0.
3.2.02026-11-0990124Add an optional incremental sync mode and a start_date setting to the page_insights stream, which reads a since and until date range in 90-day windows.
3.1.02026-11-0990123Configurable insights metrics and period, new video, Reels, comment and rating streams, incremental posts
3.0.22026-11-0990130Exchange the Page access token once per sync instead of before every request, and resolve the schema’s date-time paths once per stream instead of per record
3.0.12026-11-0490914Require Python 3.11 for future CDK compatibility.
3.0.02026-10-1385780Remove the Meta-deprecated legacy Page fields current_location, genre, network, parking, and start_info, and the live_videos edge, from the page stream. Remove current_location, genre, and network from nested page objects in the page and post streams.
2.1.42026-09-2286489Retry Facebook’s “Please reduce the amount of data you’re asking for” error again instead of failing the sync as a configuration error.
2.1.32026-09-0878077Fail fast on deterministic Facebook API bad request errors as config errors, surface the Facebook error message, and keep retrying rate-limit and transient errors.
2.1.22026-08-1784408Remove Page/Post Insights metrics deprecated by Meta and request page_total_media_view_unique / post_total_media_view_unique instead; fail fast with Meta’s own message on invalid-metric errors.
2.1.12026-05-2278342Classify Facebook app-approval errors as configuration errors.
2.1.02026-03-0272949Use QueryProperties with JsonSchemaPropertySelector to limit API field requests to user-selected fields; add configurable page_size for post and post_insights streams
2.0.42026-01-2972253Remove product_catalogs from fields request parameter
2.0.32025-12-0170248Use correct pagination parameter name (limit instead of page_size)
2.0.22025-12-0170258Use Post stream for check, handle 400 error in Page stream
2.0.12025-11-2770242Refresh in-app documentation to reflect v24 API version
2.0.02025-11-1969714Upgrade Facebook API to v24.0
1.1.42025-08-1464141Upgrade Facebook API to v23.0
1.1.32025-07-1260391Update dependencies
1.1.22025-05-1060043Update dependencies
1.1.12025-05-0353787Update dependencies
1.1.02025-04-3059126Re-enable in cloud and update versions
1.0.322025-02-0152793Update dependencies
1.0.312025-01-2752122Upgrade Facebook API to v21.0
1.0.302025-01-2552373Update dependencies
1.0.292025-01-1851637Update dependencies
1.0.282025-01-1151056Update dependencies
1.0.272025-01-0450923Update dependencies
1.0.262024-12-2850530Update dependencies
1.0.252024-12-2149997Update dependencies
1.0.242024-12-1449154Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
1.0.232024-10-2947737Update dependencies
1.0.222024-10-2147025Update dependencies
1.0.212024-10-1246807Update dependencies
1.0.202024-10-0546461Update dependencies
1.0.192024-09-2846133Update dependencies
1.0.182024-09-2145734Update dependencies
1.0.172024-09-1445563Update dependencies
1.0.162024-09-0745311Update dependencies
1.0.152024-08-3145052Update dependencies
1.0.142024-08-2444664Update dependencies
1.0.132024-08-1744234Update dependencies
1.0.122024-08-1243729Update dependencies
1.0.112024-08-1043477Update dependencies
1.0.102024-08-0343224Update dependencies
1.0.92024-07-2742787Update dependencies
1.0.82024-07-2042255Update dependencies
1.0.72024-07-1341685Update dependencies
1.0.62024-07-1041543Update dependencies
1.0.52024-07-0941126Update dependencies
1.0.42024-07-0640812Update dependencies
1.0.32024-06-2540500Update dependencies
1.0.22024-06-2240058Update dependencies
1.0.12024-06-0639243[autopull] Upgrade base image to v1.2.2
1.0.02024-03-1436015Upgrade Facebook API to v19.0
0.3.02023-06-2627728License Update: Elv2
0.2.52023-04-1326939Add advancedAuth to the connector spec
0.2.42023-04-1325143Update insight metrics request params
0.2.32023-02-2323395Parse datetime to rfc3339
0.2.22023-02-1022804Retry 500 errors
0.2.12022-12-2920925Fix tests; modify expected records
0.2.02022-11-2419788Migrate lo low-code; Beta certification; Upgrade Facebook API to v.15
0.1.62021-12-229032Remove deprecated field live_encoders from Page stream
0.1.52021-11-268267updated all empty objects in schemas for Page and Post streams
0.1.42021-11-26Remove unsupported insights_export field from Pages request
0.1.32021-10-287440Generate Page token from config access token
0.1.22021-10-187128Upgrade Facebook API to v.12
0.1.12021-09-306438Annotate Oauth2 flow initialization parameters in connector specification
0.1.02021-09-015158Initial Release
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.