Install & Compatibility
Where this runs
tested against v26.0.1 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.406s · 66.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.1s · import 0.376s · 69MB
66MB installed
● package 66MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FacebookAdsApi
✓ from facebook_business.api import FacebookAdsApi
✗ from facebookads.api import FacebookAdsApi
The 'facebookads' package is an older, deprecated SDK. The correct package is 'facebook_business'.
AdAccount
✓ from facebook_business.adobjects.adaccount import AdAccount
Initializes the Facebook Business SDK and fetches a list of campaigns from a specified ad account. Requires an App ID, App Secret, Access Token, and Ad Account ID with appropriate permissions.
import os
from facebook_business.api import FacebookAdsApi
from facebook_business.adobjects.adaccount import AdAccount
# --- Configuration (replace with your actual values or environment variables) ---
# Get these from your Facebook Developer App settings
APP_ID = os.environ.get('FB_APP_ID', 'YOUR_APP_ID')
APP_SECRET = os.environ.get('FB_APP_SECRET', 'YOUR_APP_SECRET')
ACCESS_TOKEN = os.environ.get('FB_ACCESS_TOKEN', 'YOUR_ACCESS_TOKEN')
# Get this from your Facebook Ad Account
AD_ACCOUNT_ID = os.environ.get('FB_AD_ACCOUNT_ID', 'act_YOUR_AD_ACCOUNT_ID') # Prefix with 'act_'
# Initialize the API
FacebookAdsApi.init(app_id=APP_ID, app_secret=APP_SECRET, access_token=ACCESS_TOKEN)
try:
# Create an AdAccount object
account = AdAccount(AD_ACCOUNT_ID)
# Fetch campaigns for the ad account
campaigns = account.get_campaigns(fields=[AdAccount.Field.name, AdAccount.Field.status])
print(f"Campaigns for Ad Account {AD_ACCOUNT_ID}:")
for campaign in campaigns:
print(f" - ID: {campaign['id']}, Name: {campaign['name']}, Status: {campaign['status']}")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure your APP_ID, APP_SECRET, ACCESS_TOKEN, and AD_ACCOUNT_ID are correct ")
print("and that your access token has the necessary permissions (e.g., 'ads_read', 'ads_management').")
Debug
Known issues
breakingAdvantage+ Shopping Campaigns (ASC) and Advantage+ App Campaigns (AAC) can no longer be created or updated via the Marketing API starting v25.0. This change extends to all versions by May 19, 2026, as part of the Automation Unification toward Advantage+ setup.fixMigrate to the new Advantage+ campaign structure using Advantage+ audience, campaign budget, and placements. Refer to Meta's Advantage+ Campaigns documentation for migration guidance.
affects: >= 25.0.0, all versions after May 19, 2026
breakingDynamic Media is enabled by default for Advantage+ Catalog ads via the Marketing API starting v24.0.fixDevelopers must explicitly opt out of Dynamic Media if it is not desired for Advantage+ Catalog ads. Review your API integrations to adjust this setting before September 1, 2025, with full enforcement by October 20, 2025.
affects: >= 24.0.0
breakingThe Facebook video feeds ad placement is no longer available in Marketing API v24.0. Attempts to use it will result in errors.fixUpdate ad set configurations to remove the Facebook video feeds placement. The Facebook Reels placement is the recommended replacement.
affects: >= 24.0.0
deprecatedSeveral legacy metrics, including Page Reach, Impressions, and 3-second Viewers, are planned for deprecation in June 2026.fixTransition to using the new `Media Views` and `Media Viewers` metrics which will replace the deprecated legacy metrics.
affects: All versions, effective June 2026
gotchaThe SDK relies on specific API versions. If the API version used in your calls (or the default set by the SDK) becomes deprecated, your requests will fail with a 'deprecated version' error.fixEnsure your application explicitly targets or is compatible with a currently supported Marketing API version (e.g., v25.0). Meta typically supports older API versions for a 90-day grace period after a new version is released.
affects: All versions
gotchaAccess tokens have a limited lifespan and require correct permissions. Expired tokens or insufficient permissions (e.g., `ads_read`, `ads_management`) are common causes of API call failures.fixRegularly refresh access tokens, particularly long-lived ones. Verify that your app and user access tokens have all necessary permissions/scopes for the API calls being made.
affects: All versions
breakingThe SDK encountered an AttributeError `type object 'Field' has no attribute 'status'`, suggesting an incompatibility with the Marketing API's data structures or an SDK bug. This often occurs when the SDK version does not align with the API version being called.fixUpdate the SDK to its latest version. If the problem persists, ensure your application explicitly targets an API version known to be compatible with your SDK version, and review Meta's Marketing API changelog for updates to object structures.
affects: Specific SDK/API version combinations
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'facebook_business.objects'
The Python import statement is attempting to access a module path that no longer exists or is incorrect in the `facebook-business` SDK. The common ad objects are typically found under `facebook_business.adobjects`.
fixChange the import statement to use `facebook_business.adobjects` for specific objects like AdCampaign, AdAccount, etc. For example, `from facebook_business.adobjects.adcampaign import AdCampaign`.
ValueError: You must initialize FacebookAdsApi before making any calls.
The FacebookAdsApi object, which handles authentication and API versioning, has not been properly initialized with your app ID, app secret, and access token before attempting to make any API requests.
fixCall `FacebookAdsApi.init(app_id=MY_APP_ID, app_secret=MY_APP_SECRET, access_token=MY_ACCESS_TOKEN)` at the beginning of your script or before making any API calls.
FacebookRequestError: Invalid access token: The access token could not be decrypted
The access token provided to the API is either expired, invalid, malformed, or does not have the necessary permissions for the requested operation.
fixGenerate a new, valid user access token or app access token from the Meta Developer Dashboard with the required permissions for your application. Ensure the token is not expired and is correctly included in your API initialization.
Upgrade
Version history
26.0.1latest on PyPI · released Aug 25, 2026
Audit
Dependencies
No dependency data recorded yet.