facebook-python-business-sdk: autogenerated ad objects, one init call, and a licence you must read

One SDK instead of five APIs

The reason this package exists is stated as a cost problem. Partners are using multiple Facebook APIs to serve the needs of their clients, and adopting all of them and keeping them up to date across the various platforms can be time consuming and ultimately prohibitive.

The Business SDK bundles many of Meta's APIs into one SDK to ease implementation and upkeep. It is an upgraded version of the Marketing API SDK that includes the Marketing API plus APIs from different platforms such as Pages, Business Manager and Instagram.

That history explains the naming and the residue. The package is called facebook_business, but the getting-started snippet still refers to installing facebookads with pip and to an egg-info directory named facebook_business-3.0.0-py2.7, and the API class is FacebookAdsApi. The README also notes the package is compatible with Python 2 and 3, which is a leftover from the era it is written for.

Version 26.0.2 is current, released 2026-09-21, after 26.0.1 on 2026-08-25 and 26.0.0, tagged as Meta Business SDK v26.0.0, on 2026-08-06. The available releases move from 26.0.0 to 26.0.1 and 26.0.2.

Install, init, and the first call

Installation is a pip install of the published package.

pip install facebook_business

For Python 3, use `pip3` and `python3` instead. If you want the newest version rather than whatever is on pypi.python.org, the alternative is to check out the repository or download a release tarball and install it from source with `python setup.py install`.

Bootstrapping takes an app id, an app secret and an access token, all passed to a single init call.

from facebook_business.api import FacebookAdsApi
from facebook_business.adobjects.adaccount import AdAccount

my_app_id = 'your-app-id'
my_app_secret = 'your-appsecret'
my_access_token = 'your-page-access-token'
FacebookAdsApi.init(my_app_id, my_app_secret, my_access_token)
my_account = AdAccount('act_<your-adaccount-id>')
campaigns = my_account.get_campaigns()
print(campaigns)

The example constructs the account ID as `act_<your-adaccount-id>`.

Note that init is a class-level global call rather than a client object you pass around. Everything you create afterwards uses that configuration, which is convenient in a script and awkward in a service that talks to several accounts with different tokens.

Autogenerated adobjects, and which methods appear

The design of the object layer is the core of the SDK.

All objects on the graph are instances of `AbstractObject`. Some can be queried directly and are instances of `AbstractCrudObject`, a subclass, and both abstract classes live in `facebook_business.adobjects`.

Under adobjects there is a file for every ad object in the Marketing API. These files are autogenerated from the API and therefore close in parity with what the API offers, which is the practical benefit: when Meta adds a field, the class follows.

What you see on a class depends on which CRUD operations it supports. The method names are `api_get`, `api_update`, `api_delete`, plus `create_xxx` and `get_xxx` shaped accessors. Campaign has all of these; AdAccount does not. So the class surface is a readable summary of what the API permits on that object.

There is a deprecation warning attached to it. Several functions in `AbstractCrudObject` are deprecated, including `remote_create`, `remote_read`, `remote_update` and `remote_delete`, and the README asks you to stop using them because they may be deprecated soon. That is an unusual thing to read in an official README and tells you the API surface has churned once already.

Prerequisites are where this project actually fails

Most of the README's length is about setup, and that is not padding.

You must have an app registered on developers.facebook.com. To manage the Marketing API you then add the Marketing API product in your App Dashboard. The README calls one setting out explicitly with IMPORTANT: for security, it is recommended to turn on App Secret Proof for Server API calls in your app's Settings -> Advanced page.

Access tokens come next. When someone connects with an app using Facebook Login and approves a permission request, the app obtains an access token that provides temporary secure access to Facebook APIs. The token is an opaque string identifying a User, app, or Page.

The mapping between API and permission is specific. For the Marketing API you need a user access token for your app and the `ads_management` permission. For the Pages API you need a Page access token and the `manage_page` permission.

For getting a token while you are developing, the README points to the Graph Explorer. And it names the failure you will hit: if your script complains about an expired token, repeat the process for requesting a Page Access Token.

Access tokens here are described as temporary, which means any long-running service needs a refresh path that the README does not cover.

Five dependencies, and a custom licence

requirements.txt is short.

requests >= 2.3.0
six >= 1.7.3
curlify >= 2.1.0
pycountry >= 19.8.18
capi-param-builder-python >= 1.3.0
aiohttp; python_version >= '3.5.3'

The licence is the item to settle before you commit. setup.py carries a Facebook copyright notice granting a non-exclusive, worldwide, royalty-free licence to use, modify and distribute the software in source or binary form for use in connection with the web services and APIs provided by Facebook. It then adds that use is subject to the Facebook Developer Principles and Policies, that the notice shall be included in all copies or substantial portions, and the usual warranty disclaimer.

GitHub classifies it as Facebook Platform rather than an OSI licence, which is accurate. The practical reading: you can use and redistribute it under those terms, you must keep the notice, and your use of the underlying platform is governed by Meta's policies rather than by this file. Whether that combination fits your compliance process is a question for whoever owns it, not something the licence text decides.

Examples that enumerate the API, and how to test

The examples directory is unusual and worth understanding, because it changes what the examples are for.

The file names are not tutorials. They are generated-looking names such as AdAccountAdCreativesPostCreateAdCreativeCanvasDV.py, AdAccountAdSetsPostCreateCpa.py, AdAccountAdLabelsPost.py and AdAccountAdSetsPostBehaviorTargeting.py, one per API edge and variant. There are many dozens of them.

That makes the directory a reference index of what the API can do, indexed by the exact call you need rather than by task. If you are looking for how to post an ad set with behaviour targeting, the filename tells you before you read a line.

Testing setup is conventional: tox.ini and requirements-tests.txt at the root, with a package layout listed in setup.py that includes `facebook_business`, `facebook_business.test`, `facebook_business.utils`, `facebook_business.adobjects` and helper packages under adobjects.

There is also config.json.example at the root, which is the usual home for credentials in this ecosystem.

The alternative to this SDK is calling the Graph API directly with `requests`, which is entirely reasonable for a handful of endpoints and which many teams do anyway. What you give up is the generated object model and its coverage of the long tail of ad object variants; what you keep is no generated client, no init global, and no licence terms beyond the platform policies.

Editorial conclusion

Adopt facebook_business if you are running ad automation against Meta's Marketing API from Python, because the generated adobjects tree means new API fields appear without you writing a client for them. Do not adopt it for a small script that only reads one account, since calling the Graph API over requests is shorter than initialising the SDK and learning its object model. Before you build, create an app on developers.facebook.com, add the Marketing API product, and turn on App Secret Proof for Server API calls, since the README marks that as recommended for security rather than optional.

Frequently asked questions

Official sources

1. facebook/facebook-python-business-sdk on GitHub
2. Issues
3. Project website
4. README
5. Releases