Registry /
workflow / apache-airflow-providers-facebook
This provider package integrates Apache Airflow with Facebook APIs, offering operators and hooks to interact with various Facebook services like Marketing and Prophet. It allows data engineers to programmatically manage and automate data workflows involving Facebook platforms. Current version is 3.9.4, with releases tied to the Apache Airflow release cycle.
Install & Compatibility
Where this runs
tested against v3.9.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 294MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 26.8s · import 0.000s · 294MB
295MB installed
● package 295MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FacebookMarketingOperator
✓ from airflow.providers.facebook.marketing.operators.marketing import FacebookMarketingOperator
✗ from airflow.providers.facebook.marketing.operators.marketing import FacebookMarketingOperator
This example DAG uses the `FacebookMarketingOperator` to fetch a list of ad accounts associated with the configured Facebook connection. It requires an Airflow connection named `facebook_marketing_default` with a valid Facebook Access Token. The access token can be stored in the 'Password' field or as part of the 'Extra' JSON for the connection.
from __future__ import annotations
import pendulum
import os
from airflow.models.dag import DAG
from airflow.providers.facebook.marketing.operators.marketing import FacebookMarketingOperator
# NOTE: Ensure you have an Airflow Connection named 'facebook_marketing_default'
# with your Facebook Access Token (e.g., in the 'Password' field or 'Extra' JSON).
# Example Extra: {"access_token": "YOUR_ACCESS_TOKEN", "api_version": "v19.0"}
with DAG(
dag_id="facebook_marketing_example",
start_date=pendulum.datetime(2023, 1, 1, tz="UTC"),
schedule=None,
catchup=False,
tags=["facebook", "marketing", "example"],
doc_md="""
### Facebook Marketing Example DAG
A simple DAG demonstrating how to use the FacebookMarketingOperator to fetch ad accounts.
Requires a 'facebook_marketing_default' Airflow connection with an access token.
"""
) as dag:
get_ad_accounts = FacebookMarketingOperator(
task_id="get_ad_accounts",
facebook_conn_id="facebook_marketing_default",
api_method="GET",
api_path="/me/adaccounts",
fields=["id", "name", "account_status"],
result_processor=lambda result: print(f"Fetched Ad Accounts: {result}")
)
Debug
Known issues
breakingFacebook API versions frequently introduce breaking changes or deprecate endpoints. The provider's functionality is tightly coupled to the underlying Facebook Marketing API version. Ensure your `api_version` in the Airflow connection or operator parameters matches a supported and active Facebook API version to avoid unexpected errors.fixRegularly check Facebook Marketing API documentation for updates. Update `api_version` in your Airflow connection's 'Extra' field (e.g., `{"api_version": "v19.0"}`) or directly in the operator parameters if issues arise after Facebook API updates. affects: All versions, depends on Facebook API changes
gotchaThe provider relies on the `facebook-business` Python SDK. Incompatibilities can arise if your `facebook-business` package version is not aligned with the provider's expectations or if there are conflicts with other libraries. This can lead to unexpected runtime errors.fixRefer to the `apache-airflow-providers-facebook` PyPI page or GitHub for specific `facebook-business` dependency ranges. Consider using a virtual environment and pinning dependency versions to ensure stability.
affects: All versions
gotchaAuthentication failures are common due to expired or invalid Facebook Access Tokens. Airflow connections for Facebook Marketing typically require a long-lived access token, which can still expire or be invalidated by Facebook security policies.fixEnsure your Airflow connection (`facebook_conn_id`) uses a current and valid Facebook Access Token. Regularly check the token's validity in Facebook's developer tools and refresh if necessary. Consider using environment variables or a secrets backend for sensitive tokens instead of directly in the connection UI.
affects: All versions
gotchaFacebook APIs have strict rate limits. Making too many requests in a short period can lead to throttling errors (e.g., HTTP 429). The provider itself does not inherently handle complex rate-limit backoff strategies for user-defined tasks.fixImplement retry mechanisms with exponential backoff in your DAGs for tasks interacting with Facebook APIs. Design your DAGs to minimize concurrent requests and distribute load. Refer to Facebook's API rate limiting documentation.
affects: All versions
Audit
Dependencies
apache-airflowrequiredThis is an Airflow provider, requiring Apache Airflow core to function.
facebook-businessrequiredThe provider uses the Facebook Business SDK to interact with Facebook APIs.