Audience Network Reporting API

The Audience Network Reporting API lets you automate downloading performance data for your apps. This guide walks through key API features and use cases.

You need a user access token with read_audience_network_insights permission or an app access token to query the Reporting API. You can find a list of access tokens for the apps you manage here. Please note that you need to be an administrator of the app to see those.

Calling The API

The Audience Network reporting API is based on the App Insights API. Before reading further, please refer to this guide to learn how to read data from App Insights.

All data is returned in GMT - 8 time zone.

To call the Audience Network reporting API, use the /app_event edge with one of the event names listed below. For example, this is the API call to get impression count:

https://graph.facebook.com/<API_VERSION>/<APP_ID>/app_insights/app_event/?
  since=1398754800&
  until=1407394800&
  summary=true&
  event_name=fb_ad_network_imp&
  aggregateBy=COUNT&
  access_token=<ACCESS_TOKEN>

Here is a list of supported event names and the metric returned by each.

Name Description Supported Aggregation

fb_ad_network_request

Number of ad requests

COUNT

fb_ad_network_request

Number of filled ad requests

SUM

fb_ad_network_imp

Number of impressions

COUNT

fb_ad_network_click

Number of clicks

COUNT

fb_ad_network_video_view

Number of 10 seconds video views

COUNT

fb_ad_network_revenue

Estimated revenue

SUM

Optionally, use one of the following options in the breakdowns param to specify which metric to return:

Name Description

country

Provides a breakdown by country

placement

Provides a breakdown by placement

In cases where the sample size for the country is too low, the breakdown will not be provided and will instead be indicated by the key value of "REDACTED".

Examples

Getting the total number of impressions per day

Running the following URL with your app ID and app access token:

https://graph.facebook.com/<API_VERSION>/<APP_ID>/app_insights/app_event/?
  since=1398754800&
  until=1407394800&
  summary=true&
  event_name=fb_ad_network_imp&
  aggregateBy=COUNT&
  access_token=<ACCESS_TOKEN>

Should yield a response similar to this:

{
   "data": [
      {
         "time": "2014-07-20T07:00:00+0000",
         "value": "1023"
      },
      {
         "time": "2014-07-21T07:00:00+0000",
         "value": "1801"
      },
      {
   ],
   "summary": {
      "name": "Custom Events",
      "period": "daily",
      "since": "2014-04-29T07:00:00+0000",
      "until": "2014-08-07T07:00:00+0000"
   }
}

Getting the estimated revenue by placement, per day

Running the following URL with your app ID and app access token:

https://graph.facebook.com/<API_VERSION>/<APP_ID>/app_insights/app_event/?
  since=1398754800&
  until=1407394800&
  summary=true&
  event_name=fb_ad_network_revenue&
  aggregateBy=SUM&
  breakdowns[0]=placement&
  access_token=<ACCESS_TOKEN>

Should yield a response similar to this:

{
   "data": [
      {
         "time": "2014-07-20T07:00:00+0000",
         "value": "0.3269935",
         "breakdowns": {
            "placement": "698231856892493"
         }
      },
      {
         "time": "2014-07-21T07:00:00+0000",
         "value": "0.7273753",
         "breakdowns": {
            "placement": "698231856892493"
         }
      },
      {
         "time": "2014-07-22T07:00:00+0000",
         "value": "1.18529407",
         "breakdowns": {
            "placement": "698231856892493"
         }
      }
   ],     
   "summary": {
      "name": "Custom Events",
      "period": "daily",
      "since": "2014-04-29T07:00:00+0000",
      "until": "2014-08-07T07:00:00+0000"
   }
}

App Level Reporting

Another scenario is pulling reporting metrics by app for multiple apps. Use the following URL specifying your user ID and the following parameters:

Parameter Description Required?

app_ids

Set of apps to pull metrics for. User must have permission to view insights for each app.

Yes

event_name

Metric to return

Yes

aggregateBy

COUNT or SUM as described above

Yes

breakdowns

app, placement, or country

No

since

Start time

Yes

until

End time

No

access_token

User access token

Yes

For example, this GET request:

https://graph.facebook.com/v2.5/<USER_ID>/adnetworkanalytics?
  app_ids[0]=123&
  app_ids[1]=456&
  event_name=fb_ad_network_imp&
  breakdowns[0]=app&
  since=1439017200&
  until=1440054000 &
  aggregateBy=COUNT&
  access_token=<ACCESS_TOKEN>

Will yield a response similar to this:

{
   "data": [
      {
         "time": "2015-08-18T08:00:00+0000",
         "value": "15543566",
         "breakdowns": {
            "app": "123"
         }
      },
      {
         "time": "2015-08-16T08:00:00+0000",
         "value": "666856233",
         "breakdowns": {
            "app": "456"
         }
      },
      {
         "time": "2015-08-17T08:00:00+0000",
         "value": "706350996",
         "breakdowns": {
            "app": "456"
         }
      },
      {
         "time": "2015-08-18T08:00:00+0000",
         "value": "707091170",
         "breakdowns": {
            "app": "456"
         }
      },
      {
         "time": "2015-08-19T08:00:00+0000",
         "value": "707258270",
         "breakdowns": {
            "app": "456"
         }
      },
      {
         "time": "2015-08-20T08:00:00+0000",
         "value": "311536156",
         "breakdowns": {
            "app": "456"
         }
      }
   ]
}

Common Use Cases

One of the common use cases of using the reporting API is to obtain the daily RPM. In order to calcualte this value you will want to do the following:

  1. Obtain the daily total revenue: make an API call to get the SUM of fb_ad_network_revnue
  2. Total impressions: make an API call to get the COUNT of fb_ad_network_imp
  3. Once you have the results, divide the daily number you get from step 1 by the count of step 2 and multiple by 1000.