facebook / facebook-python-business-sdk

Python SDK for Meta Marketing APIs

Facebook Business SDK for Python

Introduction

The Facebook Business SDK is a one-stop-shop to help our partners better serve their businesses. Partners are using multiple Facebook API's to serve the needs of their clients. Adopting all these API's and keeping them up to date across the various platforms can be time consuming and ultimately prohibitive. For this reason Facebook has developed the Business SDK bundling many of its APIs into one SDK to ease implementation and upkeep. The Business SDK is an upgraded version of the Marketing API SDK that includes the Marketing API as well as many Facebook APIs from different platforms such as Pages, Business Manager, Instagram, etc.

Quick Start

Business SDK Getting Started Guide

Python is currently the most popular language for our third-party developers. facebook_business is a Python package that provides an interface between your Python application and Facebook's APIs within the Business SDK. This tutorial covers the basic knowledge needed to use the SDK and provides some exercises for the reader.

NOTE: facebook_business package is compatible with Python 2 and 3!

Pre-requisites

Register An App

To get started with the SDK, you must have an app registered on developers.facebook.com.

To manage the Marketing API, please visit your App Dashboard and add the Marketing API product to your app.

IMPORTANT: For security, it is recommended that you turn on 'App Secret Proof for Server API calls' in your app's Settings->Advanced page.

Obtain An Access Token

When someone connects with an app using Facebook Login and approves the request for permissions, the app obtains an access token that provides temporary, secure access to Facebook APIs.

An access token is an opaque string that identifies a User, app, or Page.

For example, to access the Marketing API, you need to generate a user access token for your app and ask for the ads_management permission; to access Pages API, you need to generate a Page access token for your app and ask for the manage_page permission.

Refer to our Access Token Guide to learn more.

For now, we can use the Graph Explorer to get an access token.

Install package

The easiest way to install the SDK is via pip in your shell.

NOTE: For Python 3, use pip3 and python3 instead.

NOTE: Use sudo if any of these complain about permissions. (This might happen if you are using a system installed Python.)

If you don't have pip:

easy_install pip

Now execute when you have pip:

pip install facebook_business

If you care for the latest version instead of a possibly outdated version in the pypi.python.org repository, check out the repository from GitHub or download a release tarball. Once you've got the package downloaded and unzipped, install it:

python setup.py install

Great, now you are ready to use the SDK!

Bootstrapping

Create test.py

Create a test.py file with the contents below (assuming your system is using python 2.7 and installed under /opt/homebrew. Update to your proper python location.):

import sys
sys.path.append('/opt/homebrew/lib/python2.7/site-packages') # Replace this with the place you installed facebookads using pip
sys.path.append('/opt/homebrew/lib/python2.7/site-packages/facebook_business-3.0.0-py2.7.egg-info') # same as above

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)

Test Your Install

Test your install with the following command:

python test.py

You should see the result in your terminal window. If it complains about an expired token, repeat the process for requesting a Page Access Token described in the prerequisites section above.

NOTE: We shall use the objects module throughout the rest of the tutorial. You can also use the individual class files under adobjects directly.

Understanding CRUD

The SDK implements a CRUD (create, read, update, delete) design. Objects relevant to exploring the graph are located in the objects module of the facebook_business package.

All objects on the graph are instances of AbstractObject. Some objects can be directly queried and thus are instances of AbstractCrudObject (a subclass of AbstractObject). Both these abstract classes are located in facebook_business.adobjects.

There is and additional folder adobjects under facebook_business. Under this you will see a file for every ad object in our Marketing API. These files are autogenerated from our API and therefore are close in parity with what API has to offer. Based on what CRUD operations can be performed on each object, you will see the presence of the following methods in them:

• api_get
• api_update
• api_delete
• create_xxx
• get_xxx

For example, Campaign has all these methods but AdAccount does not. Read the Marketing API documentation for more information about how different ad objects are used.

There are some deprecated function in AbstractCrudObject, like

• remote_create
• remote_read
• remote_update
• remote_delete

Please try to stop use them since we may plan to deprecated them soon.

Exploring the Graph

The way the SDK abstracts the API is by defining classes that represent objects on the graph. These class definitions and their helpers are located in facebook_business.adobjects.

Initializing Objects

Look at AbstractObject's and AbstractCrudObject's __init__ method for more information. Most objects on the graph subclass from one of the two.

When instantiating an ad object, you can specify its id if it already exists by defining fbid argument. Also, if you want to interact with the API using a specific api object instead of the default, you can specify the api argument.

Edges

Look at the methods of an object to see what associations over which we can iterate. For example an User object has a method get_ad_accounts which returns an iterator of AdAccount objects.

Ad Account

Most ad-related operations are in the context of an ad account. You can go to Ads Manager to see accounts for which you have permission. Most of you probably have a personal account.

Let's get all the ad accounts for the user with the given access token. I only have one account so the following is printed:

>>> from facebook_business.adobjects.user import User
>>> me = adobjects.User(fbid='me')
>>> my_accounts = list(me.get_ad_accounts())
>>> print(my_accounts)
[{   'account_id': u'17842443', 'id': u'act_17842443'}]
>>> type(my_accounts[0])
<class 'facebook_business.adobjects.AdAccount'>

WARNING: We do not specify a keyword argument api=api when instantiating the User object here because we've already set the default api when bootstrapping.

NOTE: We wrap the return value of get_ad_accounts with list() because get_ad_accounts returns an EdgeIterator object (located in facebook_business.adobjects) and we want to get the full list right away instead of having the iterator lazily loading accounts.

For our purposes, we can just pick an account and do our experiments in its context:

>>> my_account = my_accounts[0]

Or if you already know your account id:

>>> my_account = adobjects.AdAccount('act_17842443')

Create

Let's create a campaign. It's in the context of the account, i.e. its parent should be the account.

fields = [
]
params = {
  adobjects.Campaign.Field.name : 'Conversions Campaign',
  adobjects.Campaign.Field.configured_status: adobjects.Campaign.Status.paused,
}
campaign = AdAccount(id).create_campaign(fields, params)

Then we specify some details about the campaign. To figure out what properties to define, you should look at the available fields of the object (located in Campaign.Field) and also look at the ad object's documentation (e.g. Campaign).

NOTE: To find out the fields, look at the individual class file under adobjects directory.

If there's an error, an exception will be raised. Possible exceptions and their descriptions are listed in facebook_business.exceptions.

Read

We can also read properties of an object from the api assuming that the object is already created and has a node path. Accessing properties of an object is simple since AbstractObject implements the collections.MutableMapping. You can access them just like accessing a key of a dictionary:

>>> print(my_account)
{'account_id': u'17842443', 'id': u'act_17842443'}
>>> my_account = my_account.api_get(fields=[adobjects.AdAccount.Field.amount_spent])
>>> print(my_account[adobjects.AdAccount.Field.amount_spent])
{'amount_spent': 21167, 'account_id': u'17842443', 'id': u'act_17842443'}

Update

To update an object, we can modify its properties and then call the api_update method to sync the object with the server. Let's correct the typo "Campain" to "Campaign":

>>> campaign.api_update(fields=[], params={adobjects.Campaign.Field.name:"Potato Campaign"})

You can see the results in ads manager.

Delete

If we decide we don't want the campaign we created anymore:

campaign.api_delete()

Useful Arguments

MULTIPLE ACCESS TOKENS

Throughout the docs, the method FacebookAdsApi.init is called before making any API calls. This method set up a default FacebookAdsApi object to be used everywhere. That simplifies the usage but it's not feasible when a system using the SDK will make calls on behalf of multiple users.

The reason why this is not feasible is because each user should have its own FacebookSession, with its own access token, rather than using the same session for every one. Each session should be used to create a separate FacebookAdsApi object. See example below:

my_app_id = '<APP_ID>'
my_app_secret = '<APP_SECRET>'
my_access_token_1 = '<ACCESS_TOKEN_1>'
my_access_token_2 = '<ACCESS_TOKEN_2>'
proxies = {'http': '<HTTP_PROXY>', 'https': '<HTTPS_PROXY>'} # add proxies if needed

session1 = FacebookSession(
    my_app_id,
    my_app_secret,
    my_access_token_1,
    proxies,
)

session2 = FacebookSession(
    my_app_id,
    my_app_secret,
    my_access_token_2,
    proxies,
)

api1 = FacebookAdsApi(session1)
api2 = FacebookAdsApi(session2)

In the SDK examples, we always set a single FacebookAdsApi object as the default one. However, working with multiples access_tokens, require us to use multiples apis. We may set a default api for a user, but, for the other users, we shall use its the api object as a param. In the example below, we create two AdUsers, the first one using the default api and the second one using its api object:

FacebookAdsApi.set_default_api(api1)

me1 = AdUser(fbid='me')
me2 = AdUser(fbid='me', api=api2)

Another way to create the same objects from above would be:

me1 = AdUser(fbid='me', api=api1)
me2 = AdUser(fbid='me', api=api2)

From here, all the following workflow for these objects remains the same. The only exceptions are the classmethods calls, where we now should pass the api we want to use as the last parameter on every call. For instance, a call to the Aduser.get_by_ids method should be like this:

session = FacebookSession(
 my_app_id,
 my_app_secret,
 my_access_token_1,
 proxies,
)

api = FacebookAdsApi(session1)
Aduser.get_by_ids(ids=['<UID_1>', '<UID_2>'], api=api)

CRUD

All CRUD calls support a params keyword argument which takes a dictionary mapping parameter names to values in case advanced modification is required. You can find the list of parameter names as attributes of {your object class}.Field. Under the Field class there may be other classes which contain, as attributes, valid fields of the value of one of the parent properties.

api_update and create_xxx support a files keyword argument which takes a dictionary mapping file reference names to binary opened file objects.

api_get supports a fields keyword argument which is a convenient way of specifying the 'fields' parameter. fields takes a list of fields which should be read during the call. The valid fields can be found as attributes of the class Field.

Edges

When initializing an EdgeIterator or when calling a method such as AdAccount.get_ad_campaigns:

• You can specify a fields argument which takes a list of fields to read for the objects being read.
• You can specify a params argument that can help you specify or filter the edge more precisely.

Batch Calling

It is efficient to group together large numbers of calls into one http request. The SDK makes this process simple. You can group together calls into an instance of FacebookAdsApiBatch (available in facebook_business.api). To easily get one for your api instance:

my_api_batch = api.new_batch()

Calls can be added to the batch instead of being executed immediately:

campaign.api_delete(batch=my_api_batch)

Once you're finished adding calls to the batch, you can send off the request:

my_api_batch.execute()

Please follow batch call guidelines in the Marketing API documentation. There are optimal numbers of calls per batch. In addition, you may need to watch out that for rate limiting as a batch call simply improves network performance and each call does count individually towards rate limiting.

Exceptions

See facebook_business.exceptions for a list of exceptions which may be thrown by the SDK.

Tests

Unit tests

The unit tests don't require an access token or network access. Run them with your default installed Python as follows:

python -m facebook_business.test.unit

You can also use tox to run the unit tests with multiple Python versions:

sudo apt-get install python-tox  # Debian/Ubuntu
sudo yum install python-tox      # Fedora
tox --skip-missing-interpreters

You can increase interpreter coverage by installing additional versions of Python. On Ubuntu you can use the deadsnakes PPA. On other distributions you can build from source and then use sudo make altinstall to avoid conflicts with your system-installed version.

Examples

Examples of usage are located in the examples/ folder.

Debug

If this SDK is not working as expected, it may be either a SDK issue or API issue.

This can be identified by constructing a raw cURL request and seeing if the response is as expected

for example:

from facebook_business.adobjects.page import Page
from facebook_business.api import FacebookAdsApi

FacebookAdsApi.init(access_token=access_token, debug=True)
page = Page(page_id).api_get(fields=fields,params=params)

When running this code, this cURL request will be printed to the console as:

curl -X 'GET' -H 'Accept: */*' -H 'Accept-Encoding: gzip, deflate' -H 'Connection: keep-alive' -H 'User-Agent: fbbizsdk-python-v3.3.1' 'https://graph.facebook.com/v3.3/<pageid>/?access_token=<access_token>&fields=name%2Cbirthday%2Cphone'

SDK Codegen

Our SDK is autogenerated from SDK Codegen. If you want to learn more about how our SDK code is generated, please check this repository.

Issue

Since we want to handle bugs more efficiently, we've decided to close issue reporting in Github and move to our dedicated bug reporting channel. If you encounter a bug with Business SDK (Python), please report the issue at our developer bug reporting channel.

License

Facebook Business SDK for Python is licensed under the LICENSE file in the root directory of this source tree.

facebook-python-business-sdk's Issues

LookalikeAudience Field don't have id

I can't create a LookalikeAudience:
lookalike = LookalikeAudience(parent_id=self.ad_account_id)
It has a error "type object 'Field' has no attribute 'id". In your API, class LookalikeAudience don't have id in the Field class. Is this a bug?

filename param for AdImage

filename is definitely a string containing path and name. But sometimes it would be useful passing just a file-like object because we have the file only in memory. We could modify the methods to process also file object but the parameter's name is still filename. So it could be misleading.
Any suggestion?

The new version should be updated to v2.4

I just changed the version in api.py to:
API_VERSION = 'v2.4'

Allow CustomAudiences to upload pre-hashed email addresses

Currently you are unable to upload pre-hashed SHA-256 hashes since the add_user function does the hashing automatically. There should be an option or logic implemented to upload emails that are already hashed

Optionally remove use of appsecret_proof

Is there any chance you think it would be a good idea to make the use of appsecret_proof optional? It fails for me every time I try to create a session with it. Obviously works fine if I remove it.

https://github.com/facebook/facebook-python-ads-sdk/blob/master/facebookads/session.py#L66

Thank you,
Freddy

Cannot create AdLabel on AdCreative

Nowhere in the API documentation is mentioned the fact that it is possible to add labels on creatives. So I think you code should be updated and remove the HasAdLabel mixin inheritance from the AdCreative class here. If I'm mistaken, your API doc should be updated...

Got the following error:

in call raise fb_response.error() FacebookRequestError: Message: Call was not successful Method: GET Path: https://graph.facebook.com/v2.4/6034071669641/adlabels Params: {'summary': 'true'} Status: 400 Response: { "error": { "message": "(#100) Invalid edge (adlabels) on node type (AdCreative)", "code": 100, "type": "OAuthException", "fbtrace_id": "DElUVn10w2E" } }

How filter results of get_insights?

I cannot find problem with my code.

from __future__ import absolute_import, division, print_function
from facebookads.api import FacebookAdsApi
from facebookads import objects
from pprint import pprint

FacebookAdsApi.init(app_id, app_secret,
                    access_token)
me = objects.AdUser(fbid='me')

for account in me.get_ad_accounts():
    for i in account.get_insights(fields=[
        objects.Insights.Field.spend,
        objects.Insights.Field.campaign_name,
        objects.Insights.Field.campaign_id,
    ], params={'date_preset': 'last_7_days', 'level': 'campaign', 'filtering':
        [
            {
                'field': 'campaign_name',
                'operator': 'CONTAIN',
                'value': 'hrooom-brooom',
            },
            {
                'field': 'spend',
                'operator': 'GREATER_THAN',
                'value': 0,
            },
        ]
               }):
        pprint(i)

i try filter campaigns by part campaign_name (its postfix in real), but returns all campaigns of account. Where is my mistake?

Unable get ad accounts

When I get my ad accounts, it throw a exceptions "AttributeError: 'unicode' object has no attribute 'get'".

File "/app/services/ads/facebook.py", line 1016, in
FacebookAPI = FacebookAds(my_app_id, my_app_secret, my_access_token)
File "/app/services/ads/facebook.py", line 51, in init
self.my_accounts = list(me.get_ad_accounts())
File "/app/.heroku/python/lib/python2.7/site-packages/facebookads/objects.py", line 797, in get_ad_accounts
return self.iterate_edge(AdAccount, fields, params)
File "/app/.heroku/python/lib/python2.7/site-packages/facebookads/objects.py", line 745, in iterate_edge
params=params
File "/app/.heroku/python/lib/python2.7/site-packages/facebookads/objects.py", line 94, in init
self.load_next_page()
File "/app/.heroku/python/lib/python2.7/site-packages/facebookads/objects.py", line 137, in load_next_page
params=self._params,
File "/app/.heroku/python/lib/python2.7/site-packages/facebookads/api.py", line 307, in call
raise fb_response.error()
File "/app/.heroku/python/lib/python2.7/site-packages/facebookads/api.py", line 117, in error
self.body()
File "/app/.heroku/python/lib/python2.7/site-packages/facebookads/exceptions.py", line 76, in init
if self._error.get('error_data', {}).get('blame_field_specs'):
AttributeError: 'unicode' object has no attribute 'get'

How to call custom urls and read data with exception handling?

example
read existing product sets with field names
http://graph.facebook.com/{product_catalogue_id}/product_sets?fields=product_count,name

AdUser.get_ad_account doesn't flow api instance to AdAccount

When I create an AdUser with a specific api instance and then call get_ad_account on that instance the api instance does not flow to the created AdAccount.

Here is a test case that reproduces this issue:

    app_id = config['app_id']
    app_secret = config['app_secret']
    access_token = config['access_token']
    def test_get_ad_account_from_ad_user():
        assert FacebookAdsApi.get_default_api() == None # Ensure the default api is not set
        session = FacebookSession(
            app_id,
            app_secret,
            connection.access_token,
        )
        api = FacebookAdsApi(session)
        me = AdUser(fbid='me', api=api)
        ad_account = me.get_ad_account()
        assert ad_account.get_api() == api

Missing video views objective

The objective class is missing the VIDEO_VIEWS property.

KeyError: 'blame_field_specs'

While creating adsets using batch

Traceback (most recent call last):
  File "./manage.py", line 32, in <module>
    execute_from_command_line(sys.argv)
  File "/home/web/work4us/venv/local/lib/python2.7/site-packages/django/core/management/__init__.py", line 399, in execute_from_command_line
    utility.execute()
  File "/home/web/work4us/venv/local/lib/python2.7/site-packages/django/core/management/__init__.py", line 392, in execute
    self.fetch_command(subcommand).run_from_argv(self.argv)
  File "/home/web/work4us/venv/local/lib/python2.7/site-packages/django/core/management/base.py", line 242, in run_from_argv
    self.execute(*args, **options.__dict__)
  File "/home/web/work4us/venv/local/lib/python2.7/site-packages/django/core/management/base.py", line 285, in execute
    output = self.handle(*args, **options)
  File "/home/web/work4us/python/sjp_app/management/commands/push_sjp_ads_campaign_csv.py", line 49, in handle
    adsets = self.create_adsets(campaign, adsets_data)
  File "/home/web/work4us/python/sjp_app/management/commands/push_sjp_ads_campaign_csv.py", line 74, in create_adsets
    batch.execute()
  File "/home/web/work4us/venv/local/lib/python2.7/site-packages/facebookads/api.py", line 439, in execute
    self._failure_callbacks[index](inner_fb_response)
  File "/home/web/work4us/venv/local/lib/python2.7/site-packages/facebookads/objects.py", line 500, in callback_failure
    failure(response)
  File "/home/web/work4us/python/ads_app/api/utils.py", line 24, in failure_default_batch_callback
    raise response.error()
  File "/home/web/work4us/venv/local/lib/python2.7/site-packages/facebookads/api.py", line 111, in error
    self.body()
  File "/home/web/work4us/venv/local/lib/python2.7/site-packages/facebookads/exceptions.py", line 75, in __init__
    self._error['error_data']['blame_field_specs']
KeyError: 'blame_field_specs'

the actual error was:

{u'error': {u'is_transient': False, u'error_subcode': 1487478, u'error_user_title': u'Invalid Geo Locations', u'error_data': {u'blame_field': u'targeting'}, u'error_user_msg': u'Invalid Geo Locations', u'code': 100, u'message': u'Invalid parameter', u'type': u'FacebookApiException'}}

remote_read with batch, response after execute is missing the requested fields.

Assume s,t are AdGroup objects with valid id's already set and that b is a FacebookAdsApiBatch object.

Without using batch:

s.remote_read(fields=[AdGroup.Field.name, AdGroup.Field.campaign_id])
t.remote_read(fields=[AdGroup.Field.name, AdGroup.Field.campaign_id])

both s,t now contains the fields name and campaign_id, however if the call is made in this way instead:

s.remote_read(fields=[AdGroup.Field.name, AdGroup.Field.campaign_id], batch=b)
t.remote_read(fields=[AdGroup.Field.name, AdGroup.Field.campaign_id], batch=b)
b.execute()

The name and campaign_id fields are not set, the response bodies from the server only has the 'id' value set.

"how different ad objects are used" link in README is broken.

This hyperlink in the readme is currently broken, and it would be a great resource to have.

iterate_edge infinite loading

Hi there,

I'm encountering some issues with the following code:

def __next__(self):
    # Load next page at end.
    # If load_next_page returns False, raise StopIteration exception
    if not self._queue and not self.load_next_page():
        raise StopIteration()

    return self._queue.pop(0)

Notice the self.load_next_page(). This is cool for scripting, because people have time to wait until the N HTTP requests are over. But I'm using this in production environment in one of our APIs. And infinite loading does not play well with cloudflare timeout. I know this is particular to my setup but I really feel like I might not be the only one encountering that problem. I manage to circumvent this by overriding the iterate_edge methods of my objects and passing a custom EdgeIterator that does not load the next page systematically. Instead, I call manually load_next_page() when needed.

I understand that you cannot change your code API only for one user, but would you consider adding a parameter (for instance infinite_loading) True by default (or False if you really like the spirit!) that would control this behaviour?

If you're interested, I can provide a PR quickly, with a proof of concept :)

Cheers

AttributeError: type object 'AdCampaign' has no attribute 'Preset'

The sample code not working

from facebookads.objects import AdCampaign

campaign = AdCampaign('<AD_CAMPAIGN_ID>')

params = {

    'date_preset': AdCampaign.Preset.last_7_days,

}

insights = campaign.get_insights(params=params)

print insights

Update Docsmith link

According to this https://github.com/facebook/facebook-python-ads-sdk/tree/master/examples/docs , it's possible to generate documentation through a tool called "DocSmith". Unfortunately, the link (https://our.intern.facebook.com/intern/wiki/Solutions_Engineering/Devsite_Dynamic_Doc_Code_Blocks) doesn't seem to point at anything anymore. Would love to see what DocSmith does since googling "Facebook DocSmith" gives me a list of people named "Doc Smith".

Is there any plan to setup integration tests?

Today we encountered a business-critic issue related to our use of this SDK (see #49).

We're thinking of implementing scripts that would test that this SDK works as expected. Also, I was wondering if you have integration tests. I'm willing to contribute to those if needed. Just say the words :)

Get account from config file in custom_audience_utils.py is incorrect

Should genereate account like this:
my_account = AdAccount('act_' + config['app_act_id'])

Otherwise, it is not working.
Because, according to the link, https://developers.facebook.com/docs/marketing-api/custom-audience-targeting/v2.3#examples

curl request with parameter: act_<AD_ACCOUNT_ID>

batch remote-create error because of id=None

Hi guys,

Thanks a lot for making this, but I meet one error when do batch remote_create of campaign/adset/ads and I am not sure whether it's a mistake.

My code like:

api_batch = api.new_batch()

 // def callback function

campaign.update({
    AdCampaign.Field.name: 'Seattle Ad Campaign',
    AdCampaign.Field.objective: AdCampaign.Objective.website_clicks,
    AdCampaign.Field.status: AdCampaign.Status.paused,
})

campaign.remote_create(batch=api_batch,success=callback_success,failure=callback_failure)

api.execute()

And it raises error like:

Traceback (most recent call last):
  File "create_ad.py", line 164, in <module>
   campaign.remote_create(batch=api_batch,success=callback_success,failure=callback_failure)
  File "/home/chutong/fb_api_test/facebookads/objects.py", line 529, in remote_create
    failure=callback_failure,
  File "/home/chutong/fb_api_test/facebookads/api.py", line 373, in add
    keyvals.append("%s=%s" % (key, urllib.parse.quote(params[key])))
  File "/usr/local/lib/python2.7/urllib.py", line 1225, in quote
    raise TypeError('None object cannot be quoted')
  TypeError: None object cannot be quoted

The reason is in

    for key in params:
            keyvals.append("%s=%s" % (key, urllib.parse.quote(params[key])))

params contains key='id' which has value None, it couldn't be treated as string here.

Should a judgement for value added here or do I make a wrong usage of batch remote create here?

Thanks for your help.

bid_type not available in AdSet object

Hello,

I am currently using version 2.4

I found that I am not able to set bid_type for the ad set that I create. There is no bid_type member available in the AdSet object. I would like to set the bid_type to CPC. The ad set that I create defaults to CPA.

How to work this issue ? Any idea how to set bid_type of the ad set to CPC

Thanks

Sibi

Tests failing in clean_id

$ python -m facebookads.test.integration
.EEEEE..E
======================================================================
ERROR: runTest (__main__.AdCampaignTestCase)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/aron/src/pp/facebook-python-ads-sdk/facebookads/test/integration.py", line 269, in runTest
    self.assert_can_delete(self.subject)
  File "/home/aron/src/pp/facebook-python-ads-sdk/facebookads/test/integration.py", line 192, in assert_can_delete
    subject.remote_delete()
  File "facebookads/objects.py", line 709, in remote_delete
    self.clear_id()
  File "facebookads/objects.py", line 448, in clear_id
    del self[self.__class__.Field.id]
  File "facebookads/objects.py", line 319, in __delitem__
    del self._changes[key]
KeyError: 'id'

======================================================================
ERROR: runTest (__main__.AdGroupTestCase)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/aron/src/pp/facebook-python-ads-sdk/facebookads/test/integration.py", line 359, in tearDown
    self.ad_set.remote_delete()
  File "facebookads/objects.py", line 709, in remote_delete
    self.clear_id()
  File "facebookads/objects.py", line 448, in clear_id
    del self[self.__class__.Field.id]
  File "facebookads/objects.py", line 319, in __delitem__
    del self._changes[key]
KeyError: 'id'

======================================================================
ERROR: runTest (__main__.AdSetTestCase)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/aron/src/pp/facebook-python-ads-sdk/facebookads/test/integration.py", line 301, in runTest
    self.assert_can_delete(self.subject)
  File "/home/aron/src/pp/facebook-python-ads-sdk/facebookads/test/integration.py", line 192, in assert_can_delete
    subject.remote_delete()
  File "facebookads/objects.py", line 709, in remote_delete
    self.clear_id()
  File "facebookads/objects.py", line 448, in clear_id
    del self[self.__class__.Field.id]
  File "facebookads/objects.py", line 319, in __delitem__
    del self._changes[key]
KeyError: 'id'

======================================================================
ERROR: runTest (__main__.AdSetTestCase)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/aron/src/pp/facebook-python-ads-sdk/facebookads/test/integration.py", line 311, in tearDown
    self.campaign.remote_delete()
  File "facebookads/objects.py", line 709, in remote_delete
    self.clear_id()
  File "facebookads/objects.py", line 448, in clear_id
    del self[self.__class__.Field.id]
  File "facebookads/objects.py", line 319, in __delitem__
    del self._changes[key]
KeyError: 'id'

======================================================================
ERROR: runTest (__main__.MultiProductAdObjectStorySpecTestCase)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/aron/src/pp/facebook-python-ads-sdk/facebookads/test/integration.py", line 435, in runTest
    self.assert_can_delete(creative)
  File "/home/aron/src/pp/facebook-python-ads-sdk/facebookads/test/integration.py", line 192, in assert_can_delete
    subject.remote_delete()
  File "facebookads/objects.py", line 709, in remote_delete
    self.clear_id()
  File "facebookads/objects.py", line 448, in clear_id
    del self[self.__class__.Field.id]
  File "facebookads/objects.py", line 319, in __delitem__
    del self._changes[key]
KeyError: 'id'

build_objects_from_response can't parse AdAccount reachestimate

Hi,

when trying to get reachestimate with an AdAccount object, build_objects_from_response can't build the object from the response.

The problem seems to be that the response includes 'data' as a dict, and not as a list. (like in the reachestimate response of AdGroups)

AdAccount response:
{
"users": 3300,
"bid_estimations": [
{
"unsupported": false,
"location": 3,
"cpa_min": 110,
"cpa_median": 202,
"cpa_max": 312,
"cpc_min": 31,
"cpc_median": 57,
"cpc_max": 87,
"cpm_min": 32,
"cpm_median": 92,
"cpm_max": 187
}
],
"estimate_ready": true,
"data": {
"users": 3300,
"bid_estimations": [
{
"unsupported": false,
"location": 3,
"cpa_min": 110,
"cpa_median": 202,
"cpa_max": 312,
"cpc_min": 31,
"cpc_median": 57,
"cpc_max": 87,
"cpm_min": 32,
"cpm_median": 92,
"cpm_max": 187
}
],
"estimate_ready": true
}
}

AdGroup response:

{
"data": [
{
"users": 160000,
"bid_estimations": [
{
"unsupported": false,
"location": 3,
"cpa_min": 114,
"cpa_median": 211,
"cpa_max": 300,
"cpc_min": 23,
"cpc_median": 41,
"cpc_max": 60,
"cpm_min": 221,
"cpm_median": 526,
"cpm_max": 925
}
],
"estimate_ready": true
}
]
}

Batch `Service temporarily unavailable` error for creation of creative with page post inline

I'm trying to create several creatives using [page post inline|]. Here is how I create the creative:

def create_creative(batch, ...):
    params[AdCreative.Field.object_story_spec] = {
            "page_id": page_id,
            "link_data": {
                "message": "<name>",
                "name": "<name>",
                "picture": "<picture-url>",
                "description": "<description>",
                "link": "<post-link>"
            }
        }
    creative = AdCreative()
    creative.remote_create(params=params, batch=batch)
    return creative

And then I do the following:

batch = api.new_batch()
creative1 = create_creative(batch, **data)
creative2 = create_creative(batch, **data)
creative3 = create_creative(batch, **data)
creative4 = create_creative(batch, **data)
creative5 = create_creative(batch, **data)
batch.execute()

The result is the following:

• 4 creatives are created properly (1, 2, 3 and 5)
• the 4th one got this error:

facebookads.exceptions.FacebookRequestError(u'Call was not successful \nRequest:\n\t{\'body\': \'<the body>', \'method\': \'POST\', \'relative_url\': \'act_104145169778295/adcreatives\'}\nResponse:\n\tHTTP Status: 500\n\tHeaders:[{u\'name\': u\'Access-Control-Allow-Origin\', u\'value\': u\'*\'}, {u\'name\': u\'Vary\', u\'value\': u\'Accept-Encoding\'}, {u\'name\': u\'Pragma\', u\'value\': u\'no-cache\'}, {u\'name\': u\'Cache-Control\', u\'value\': u\'no-store\'}, {u\'name\': u\'Content-Type\', u\'value\': u\'text/javascript; charset=UTF-8\'}, {u\'name\': u\'Facebook-API-Version\', u\'value\': u\'v2.3\'}, {u\'name\': u\'WWW-Authenticate\', u\'value\': u\'OAuth "Facebook Platform" "invalid_request" "Service temporarily unavailable"\'}, {u\'name\': u\'Expires\', u\'value\': u\'Sat, 01 Jan 2000 00:00:00 GMT\'}]\n\tBody: {"error":{"message":"Service temporarily unavailable","type":"FacebookApiException","is_transient":false,"code":2,"error_subcode":1487172,"error_user_title":"Could not save creative","error_user_msg":"Could not save creative"}}\n')

It's very strange. I'm sure it's not a pb of the SDK itself, but are you aware of any limitation for creative creation?

Thanks

Impressions returned as unicode string, not int

In the Insights documentation, the stated return type for the Impressions general field is said to be of type Int:

When I am making a get_insight call on an AdAccount object, however, the Impressions field is returned as a unicode string. Here's an example call:

account = AdAccount(account_id)

params = {
    'fields': [Insights.Field.impressions,],
    'time_range': {
        'since': '2015-05-15',
        'until': '2015-05-15',
    },
}

stats = account.get_insights(params = params)

print stats

What is returned looks like this, and calling type() on the value for "impressions" returns unicode:

[<Insights> {
    "date_start": "2015-05-15",
    "date_stop": "2015-05-15",
    "impressions": "27155"
}]

Am I missing something here, or are impressions just incorrectly being returned as a unicode string?

No module named utils

pip install facebookads
Successfully installed facebookads-2.4.0

Traceback (most recent call last):
File "demo_cpa.py", line 6, in
from facebookads import FacebookSession
File "/Library/Python/2.7/site-packages/facebookads/init.py", line 22, in
from facebookads.api import FacebookAdsApi
File "/Library/Python/2.7/site-packages/facebookads/api.py", line 30, in
from facebookads.utils import urls
ImportError: No module named utils

Insights: "roas is not valid for fields param"

This bug was validated in the Ads API v2.4 Q&A:
https://www.facebook.com/events/873155332753388/878318465570408/

Reposting this here for better issue tracking

missing facebookads.utils in setup.py

I think is necessary to add facebook.utils in setup.py to PACKAGES

PACKAGES = ['facebookads', 'facebookads.test', 'facebookads.utils']

Already accounced V2.4, however, in repo, setup.py, it is still 2.3.3, do we need to change by ourselfes?

according to official announcement.
https://developers.facebook.com/ads/blog/post/2015/07/08/marketing-api-v2_4/

Custom Audiences Example Bug

In examples/custom_audience_utils.py line 103
r = audience.add_users(schema, data)
The function add_users() requires an app_id parameter as implemented in facebookads/objects.py.

Encoding issue when calling API

Hi there,

We encountered encoding issues when trying to send Swedish or French text. We might want to adapt the following code:

        if params:
            params = _top_level_param_json_encode(params)
            keyvals = ['%s=%s' % (key, urllib.parse.quote(value))
                       for key, value in params.items()]
            call['body'] = '&'.join(keyvals)

At first, we thought (as always with encoding) that we should do it ourselves before handing data to the Api, but the issue is that when reading data, the api will return unicode object instead of basestring object, hence it makes it difficult to handle every situation. For instance:

data = {...}
data = {key: value.encode("utf-8") for key, value in data.iteritems()}
creative = AdCreative().remote_create(params=data)  # this one will work
creative.remote_read(fields=["name", ...])  # let's say the name contains utf-8
adgroup_name = "Adgroup for " + creative["name"]  # here we have utf-8
adgroup_data = {"name": "adgroup_name", ...}
adgroup = AdGroup().remote_create(params=adgroup_data)  # this call will fail

The exception will be KeyError: u'\xe9' when calling the urllib.parse.quote method.

The fix is fairly easy and easily testable, let me know if you're interested in a PR, I can provide it quickly

Checking prefix 'act_' for parent_id.

from facebookads import FacebookAdsApi
from facebookads.objects import CustomAudience

my_app_id = <APP_ID>
my_app_secret = '<APP_SECRET>'
my_access_token = '<ACCESS_TOKEN>'
FacebookAdsApi.init(my_app_id, my_app_secret, my_access_token)

AD_ACCOUNT_ID = 1431453467646932

audience = CustomAudience(parent_id='{}'.format(AD_ACCOUNT_ID))
audience.update({
    CustomAudience.Field.name: 'someName',
    CustomAudience.Field.subtype: CustomAudience.Subtype.custom,
})

audience.remote_create()

When I ran this code it throws an error. But when I change the value of parent_id to 'act_{}'.format(AD_ACCOUNT_ID)', the code ran without error. Is this by design or a bug?

I would suggest that there is a check for parent_id whether it has prefix 'act_' or not.

Batch AdImage remote creation raises I/O exception.

When calling AdImage().remote_create(batch=batch); batch.execute() the exception ValueError: I/O operation on closed file is raised.

When using the AdImage().remote_create() I found that this worked as intended and the AdImage object was returned with an 'id' and 'hash', but when attempting to do this while using a batch I ran into the I/O exception.

When looking into a possible fix for this, I tried looking at the AdImage's remote_create function (line number 1366 for me) and noticed that open_file was being closed before the batch could be executed. Commenting out the line that closed the file for the sake of testing made the call complete but an error response {u'error': {u'message': u'File <IMG_PATH> has not been attached', u'type': u'GraphBatchException'}} was returned.

Here is the script I started with:

from facebookads import FacebookSession, FacebookAdsApi
from facebookads.objects import AdAccount, AdImage

APP_ID= "<APP_ID>"
APP_SECRET = "<APP_SECRET>"
ACCESS_TOKEN="<ACCESS_TOKEN"
IMG_PATH= "<IMG PATH>"

session = FacebookSession(APP_ID, APP_SECRET, ACCESS_TOKEN)
api = FacebookAdsApi(session)
FacebookAdsApi.set_default_api(api)
account = AdAccount.get_my_account()

img = AdImage(parent_id=account.get_id_assured())
img[AdImage.Field.filename] = IMG_PATH

batch = account.get_api_assured().new_batch()

img.remote_create(batch=batch)

batch.execute()

Here is the stack trace that was outputted:

File "/Users/nilesnelson/projects/facebook-python-ads-sdk/facebookads/api.py", line 416, in execute
    files=files,
  File "/Users/nilesnelson/projects/facebook-python-ads-sdk/facebookads/api.py", line 270, in call
    files=files,
  File "/Users/nilesnelson/projects/virtualenvs/adroll/lib/python2.7/site-packages/requests/sessions.py", line 443, in request
    prep = self.prepare_request(req)
  File "/Users/nilesnelson/projects/virtualenvs/adroll/lib/python2.7/site-packages/requests/sessions.py", line 374, in prepare_request
    hooks=merge_hooks(request.hooks, self.hooks),
  File "/Users/nilesnelson/projects/virtualenvs/adroll/lib/python2.7/site-packages/requests/models.py", line 307, in prepare
    self.prepare_body(data, files, json)
  File "/Users/nilesnelson/projects/virtualenvs/adroll/lib/python2.7/site-packages/requests/models.py", line 449, in prepare_body
    (body, content_type) = self._encode_files(files, data)
  File "/Users/nilesnelson/projects/virtualenvs/adroll/lib/python2.7/site-packages/requests/models.py", line 152, in _encode_files
    rf = RequestField(name=k, data=fp.read(),
ValueError: I/O operation on closed file

Here is a test for integration.py that should do the same thing as the script:

class AdImageBatchTestCase(FacebookAdsTestCase):

    def setup_ad_image(self):
        img = objects.AdImage(
            parent_id=self.TEST_ACCOUNT.get_id_assured(),
        )
        self.delete_in_teardown(img)
        img[objects.AdImage.Field.filename] = self.TEST_IMAGE_PATH
        return img

    def test_batch_create_ad_image(self):
        img = self.create_ad_image()
        batch = FacebookAdsTestCase.TEST_API.new_batch()
        img.remote_create(batch=batch)
        batch.execute()
        self.assertNotEquals(img['id'], None)

Rename Ads API to Marketing API on documentation

And update its links.

Batch remote creation does not properly encode NoneType in id field

When adding a remote_create call to a batch an error occurs where the None value for id cannot be properly quoted by urllib.parse.quote. At this point in the add call the params should already be valid JSON thanks to _top_level_param_json_encode. Unfortunately, this function only attempts to apply json.dumps to a value if it is an instance of collections.Mapping, collections.Sequence, or bool and is not an instance of six.string_types. None evades this conditional and is left unmodified in the parameters leaving it to fail when it is passed later as a parameter.

How to fetch all fields for an FB Object?

(Sorry if I'm not clear as I can be, I'm recovering from a surgery atm)

If I want to return any fields more than just id, I have to enter fields by hand, this is a bit cumbersome:

# note I already have the API session object inside (as in the README.md example)

def fetch_ad_sets(fbid):
     # I have :class:`facebookads.objects.AdCampaign` here
    campaign = fb_objects.AdCampaign(fbid=fbid)
    campaign = campaign.remote_read(
        params={"id": fbid},
        # Get all the keys inside of a class, useful.
        # fields=[attr for attr in dir(fb_objects.AdCampaign.Field) if not callable(getattr(fb_objects.AdCampaign.Field, attr)) and not attr.startswith("__")]
        fields=[
            fb_objects.AdCampaign.Field.buying_type,
            fb_objects.AdCampaign.Field.name,
            fb_objects.AdCampaign.Field.objective,
            fb_objects.AdCampaign.Field.status,
        ]
    )

    ad_sets = campaign.get_ad_sets(
        # only returns ID's
        # fields=facebookads.objects.AdSet.get_default_read_fields()
        # returns everything I specify, but it's manual
        fields=[
            fb_objects.AdSet.Field.bid_info,
            fb_objects.AdSet.Field.bid_type,
            fb_objects.AdSet.Field.budget_remaining,
            fb_objects.AdSet.Field.campaign_group_id,
            fb_objects.AdSet.Field.created_time,
            fb_objects.AdSet.Field.daily_budget,
            fb_objects.AdSet.Field.end_time,
            fb_objects.AdSet.Field.lifetime_budget,
            fb_objects.AdSet.Field.name,
            fb_objects.AdSet.Field.start_time,
            fb_objects.AdSet.Field.status,
            fb_objects.AdSet.Field.targeting,
            fb_objects.AdSet.Field.updated_time,
        ]
    )
    for ad_set in ad_sets:
        print('FbCampaign %s Ad Set: %s' % (campaign, ad_set))
        # this would retrieve everything,
        # but everything else, including no ``field`` param returns just ``'id'`` for me.
        for ad_group in ad_set.get_ad_groups(fields=facebookads.objects.AdGroup.get_default_read_fields()):
            print('FbCampaign %s Ad Set %s Ad Group: %s' % (campaign, ad_set, ad_group))

I have tried various things to try to get the fields param to work when doing remote_read and padding directly into a object class, however, the only way fields work now is if I do it explicitly.

Here are other things I've tried:

fields=[attr for attr in dir(fb_objects.AdCampaign.Field) if not callable(getattr(fb_objects.AdCampaign.Field, attr)) and not attr.startswith("__")]

fields=facebookads.objects.AdSet.get_default_read_fields()

# not entering fields param at all

All return just the 'id'.

SSL Warning in Python 2.7.9

I am getting a warning I have never seen before when creating an audience in SDK version 2.3.1, Python version 2.7.9:

InsecurePlatformWarning: A true SSLContext object is not available. This prevents urllib3 from configuring SSL appropriately and may cause certain SSL connections to fail. For more information, see https://urllib3.readthedocs.org/en/latest/security.html#insecureplatformwarning.

After reading through the link, it appears that this is related to an incompatibility with urllib3 and Python 2.7.

Is there actually a security hole here or is this just an overly-cautious warning?

get_reach_estimate

Hello.
I try to get estiamation by this documentation https://www.facebookmarketingdevelopers.com/docs/python but i don't receive cpa_curve_data field.
What do I wrong?

Supporting Graph API outside of Ads

I know this probably connects to the Graph API for Ads data. But I was wondering if there are plans to allow to connecting to endpoints like these:

https://developers.facebook.com/docs/graph-api/reference/v2.2

Reading all Ad Group Stats for an Ad Account using Batches

I am not sure if batching will help with my problem, but I need to start from the beginning of a Campaign and process all Ad Group Stats per day. After processing 1-2 months I hit the rate limit. I would like to try batching to see if that would help with this issue.

There isn't an example of batching and using remote_read().

I know what I need to do: https://developers.facebook.com/docs/reference/ads-api/batch-requests/#adstatistics

ReportStats Asynchronous Query

There is currently no straightforward way to fetch Ad Report Stats through asynchronous queries. get_report_stats in AdAccount only allows direct GET requests. And most historical data is not accessible through it, returning error 1487535. Will this be implemented in the future?

AdAccount.get_report_stats(params, async=True)

It doesn't look like this was implemented until v2.4, but it is deprecated in v2.4 on the server-side. It exists in the documentation for v2.3, but it's not in any of the code as far as I can tell (please let me know if it is). It is in the docs for v2.4 too, but the calls are deprecated on the server side and fail! FML.

It looks like a backport would need at least AdAccount.iterage_edge_async and objects.AsyncJob.
Is there a chance we can get this backported to v2.3? I can help. Are there any huge gotchas that make such a backport difficult?

Sucks that it's in the docs, but doesn't work anywhere. Seems like v2.3 is the best shot at providing a workaround. Any guidance is greatly appreciated.

facebookads 0.2.0 installation fails

When trying to upgrade (or doing a fresh install) of facebookads 0.20 you get this error:

$ pip install --upgrade facebookads==0.2.0

Downloading/unpacking facebookads
  Downloading facebookads-0.2.0.tar.gz (377kB): 377kB downloaded
  Running setup.py (path:/home/vagrant/env/build/facebookads/setup.py) egg_info for package facebookads
    Traceback (most recent call last):
      File "<string>", line 17, in <module>
      File "/home/vagrant/env/build/facebookads/setup.py", line 46, in <module>
        with open(readme_filename) as f:
    IOError: [Errno 2] No such file or directory: '/home/vagrant/env/build/facebookads/README.md'
    Complete output from command python setup.py egg_info:
    Traceback (most recent call last):

  File "<string>", line 17, in <module>

  File "/home/vagrant/env/build/facebookads/setup.py", line 46, in <module>

    with open(readme_filename) as f:

IOError: [Errno 2] No such file or directory: '/home/vagrant/env/build/facebookads/README.md'

start_time / end_time invalid for fetching stats in hour level

I have one question that really confused me about statistics.

When I try to fetch stats in [start_time, end_time] recently, like below:

account = AdAccount("act_<ACT_ID>")
params = {
    'adgroup_ids' : <JSON ID STR>,
    'start_time' : <UNIX_TIME>,                 # 20150319:10:00, here is 1426730400
    'end_time' : <UNIX_TIME>,                  # 20150319:11:00, here is 1426734000
}
adgroup_stats_list = account.get_ad_group_stats(params=params)

for adgroup_stats in adgroup_list:
     print adgroup_stats['adgroup_id']
     print adgroup_stats['clicks']
     print adgroup_stats['impressions']
     print adgroup_stats['actions']['mobile_app_install']

it returns stats not in [10:00, 11:00] , but [0:00, current_time], it seems start_time and end_time not useful in hour level, however, when I used the API one month ago, it returns clicks and impressions in [10:00, 11:00], it seems sth changed, and I'm not sure the standard behavior for this API call.

Could anyone answer my question? thanks a lot

ProductAudienceFields

I got an "Undefined class constant 'RETENTION_SECONDS'" error using the following code:
$audience = new ProductAudience(null, 'act_<ACCOUNT_ID>');
$audience->setData(array(
ProductAudienceFields::NAME => 'Product Audience',
ProductAudienceFields::PRODUCT_SET_ID => '<PRODUCT_SET_ID>',
ProductAudienceFields::PIXEL_ID => '<PIXEL_ID>',
ProductAudienceFields::INCLUSIONS => array(array(
ProductAudienceFields::RETENTION_SECONDS => 1296000,
ProductAudienceFields::RULE => array(
'event'=>array('eq'=>'ViewContent')
)
))
));
$audience->save();

I managed to fix it by adding the following constants to the ProductAudienceFields abstract class of ProductAudienceFields.php file in FacebookAds\Object\Fields :
const RETENTION_SECONDS = 'retention_seconds';
const RULE = 'rule';

Question: What is the upgrade plan for the new "Optimization Simplification" in API v2.4?

Detailed here:
https://developers.facebook.com/docs/marketing-api/optimization_simplification

My question is, when is thew SDK going to begin supporting the new optimization fields, and is there any plan to support both types of optimization during the transition?

Thanks!

Custom Audiences --list request does not work

The URL displayed in the executing command shell is
"https://grap.facebook.com/v2.4/ [id of adaccount]/customaudiences"
while in the actual Graph Explorer on the FB website it is
"https://grap.facebook.com/v2.4/ act_ [id of adaccount]/customaudiences"

I get a "Call was not successful"/ "Unsupported get request" message, Status 400.

Website Custom Audience Creation fails

Creating a WCA is failing because pixel_id is not listed as a field.

Adding the text:

pixel_id = 'pixel_id'

Under:

class CustomAudience(AbstractCrudObject):

    class Field(object):

fixes this problem

Edit:
Pull Request here: #43

KeyError when trying to read an error

Backtrace:

File ".../facebookads/api.py", line 117, in error
self.body()
File ".../facebookads/exceptions.py", line 99, in __init__
KeyError: 'path'

Looks like the error is located here. The request_context, i.e. error._call has no key "path".

I got this on version 2.3.3 and using a batch query. Looks like this https://github.com/facebook/facebook-python-ads-sdk/blob/2.4.2/facebookads/api.py#L387-L407
is the problem (I don't see a path key)

EdgeIterator._total_count is not always set and can be VERY misleading

see those lines https://github.com/facebook/facebook-python-ads-sdk/blob/master/facebookads/objects.py#L146-L147. We expected it to be set every time, and we used the total() method that returns None, which is really bad because it silently tells that there is no stats. Instead:

• could we make sure we retrieve the total_count in every situation?
• if not possible, can we raise an Exception so that we do not fail silently?

I can come up with a PR if you want