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.

The API now supports sync (GET request) and async (POST request). Sync requests are light and immediately return data. Async requests are designed to handle heavier data loads and return a query ID for you to retrieve the data at a later time. More info below.


Calling The API

Before you begin, get familiar with the Graph API. The easiest way to understand the Graph API is to use it with the Graph API Explorer, a low-level tool you can use to query data.

You need a user access token with read_audience_network_insights and read_insights permissions to query the Reporting API. You can find a list of access tokens for the apps you manage in the Access Token Tool. Please note that you need to be an administrator of the app to see these tokens. You don’t need to enable all apps for this. You just need one app to generate a User Access Token. If your user has access to several of those apps, you are able to query data for all of them.

Check out this guide to learn about the concepts of long-lived user access tokens. You can also use System Users to generate long-lived user access tokens, these can be generated in Business Manager.

You can set the permissions on the user access token with the Graph API Explorer.

  • From My Apps, select the app you want the access token for.
  • From Get Token, select Get User Access Token and set the permissions to read_audience_network_insights and read_insights (set business_management permission if querying via Business ID).

Example sync request for Ad Network Impressions:

https://graph.facebook.com/<API_VERSION>/<APP_ID|BUSINESS_ID|PROPERTY_ID>/adnetworkanalytics/?
  metrics=['fb_ad_network_imp']&
  access_token=<ACCESS_TOKEN> 

All data is returned in GMT - 8 time zone.

Example sync request for retrieving queued data via query id you received from an async request:

https://graph.facebook.com/<API_VERSION>/<APP_ID|BUSINESS_ID|PROPERTY_ID>/adnetworkanalytics_results/?
  query_ids=['QUERY_ID']&
  access_token=<ACCESS_TOKEN> 

Required Parameters

User Access Token

DescriptionSyntax

Authentication and permissions set on the user level

access_token=<USER_ACCESS_TOKEN>

Metrics

Sync requests support one metric per request.
Async requests do not have a max on how many metrics can be included, but the more metrics included the longer the data will take to generate.

NameDescriptionSyntax

fb_ad_network_revenue

Estimated revenue

metrics=['fb_ad_network_revenue']

fb_ad_network_request

Number of ad requests

metrics=['fb_ad_network_request']

fb_ad_network_cpm

Estimated CPM

metrics=['fb_ad_network_cpm']

fb_ad_network_click

Number of clicks

metrics=['fb_ad_network_click']

fb_ad_network_imp

Number of impressions

metrics=['fb_ad_network_imp']

fb_ad_network_filled_request

Number of filled ad requests

metrics=['fb_ad_network_filled_request']

fb_ad_network_fill_rate

Rate of filled ad requests

metrics=['fb_ad_network_fill_rate']

fb_ad_network_ctr

Estimated click rate

metrics=['fb_ad_network_ctr']

fb_ad_network_show_rate

Impressins divided by Filled

metrics=['fb_ad_network_show_rate']

fb_ad_network_video_guarantee_revenue

Video guarantee revenue

metrics=['fb_ad_network_video_guarantee_revenue']

fb_ad_network_video_view

Number of 10 seconds video views

metrics=['fb_ad_network_video_view']

fb_ad_network_video_view_rate

0 second video view rate

metrics=['fb_ad_network_video_view_rate']

fb_ad_network_video_mrc

Number of 2 second video views

metrics=['fb_ad_network_video_mrc']

fb_ad_network_video_mrc_rate

2 second video view rate

metrics=['fb_ad_network_video_mrc_rate']

fb_ad_network_bidding_request

Number of bid requests

metrics=['fb_ad_network_bidding_request']

fb_ad_network_bidding_response

Number of bid responses

metrics=['fb_ad_network_bidding_response']

Optional Parameters

Breakdowns

Sync requests support two breakdowns per request.
Async requests do not have a max on how many breakdowns can be included, but the more breakdowns included the longer the data will take to generate.

NameDescriptionSyntax

country

Breakdown by the country in which the metric took place.

breakdowns=['country']

delivery_method

Breakdown by either standard or bidding when the metric comes from an ad served through AN Bidding.


Available only for Publishers using Monetization Manager

breakdowns=['delivery_method']

platform

Breakdown by the platform from which the metric was logged. Can be ios (mobile app), android (mobile app), mobile_web or instant_articles.


Available only for Publishers using Monetization Manager

breakdowns=['platform']

app

Breakdown by App ID.


breakdowns=['app']

property

Breakdown by Property ID.


breakdowns=['property']

placement

Breakdown by placement ID.

breakdowns=['placement']

deal

Breakdown by deal ID.

breakdowns=['deal']

Since/Until

Defaults to past 7 days if not included. Dates or unix timestamp supported.

NameDescriptionSyntax

since

The starting limit of the query

since=2017-09-01

until

The ending limit of the query

until=2017-09-30

Filters

Breakdowns are supported filters. They must include field, operator, and values. Currently only the in operator is supported.

NameDescriptionSyntax

country

Filter by the country in which the metric took place.

filters=[{'field':'country', 'operator':'in', 'values':['US', 'JP']}]

placement

Filter by placement ID. The value is REDACTED if less than 100.

filters=[{'field':'placement', 'operator':'in', 'values':['PLACEMENT_ID']}]

delivery_method

Filter by either standard or bidding.


Available only for Publishers using Monetization Manager.

filters=[{'field':'delivery_method', 'operator':'in', 'values':['bidding']}]

platform

Filter by the platform from which the metric was logged. Can be ios (mobile app), android (mobile app), mobile_web or instant_articles.


Available only for Publishers using Monetization Manager.

filters=[{'field':'platform', 'operator':'in', 'values':['mobile_web']}]

deal

Filter by deal ID.

filters=[{'field':'deal', 'operator':'in', 'values':['[DEAL_ID]}]

Ordering Column

Defaults to time if not included.

NameDescriptionSyntax

time

Order by the timestamp that appears in each row

ordering_column=time

value

Order by the value of each row

ordering_column=value

Ordering Type

Defaults to descending if not included.

NameDescriptionSyntax

ascending

Order from smallest to largest

ordering_type=ascending

descending

Order by largest to smallest

ordering_type=descending

Limit

NameDescriptionSyntax

limit

Integer that specifies a limit to the number of rows the response has. SYNC requests have a max row limit of 1,000 and ASYNC requests have a max row limit of 10,000

limit=500

Aggregation Period

Defaults to day if not included.

NameDescriptionSyntax

day

Aggregates the data by day

aggregation_period=day

total

Aggregates the data over the entire time range

aggregation_period=total