Reporting API

Below is a guide for integrating the Audience Network Reporting API to access performance data for your apps.

Prerequisites

• A Meta App with the Facebook Login use case and the `read_audience_network_insights` permission
• Facebook Login in your app
• A successful test query for a Graph API endpoint and the read_audience_network_insights permission
• Successful completion of Meta App Review
• A long-lived User Access Token

Recommendations

• When requesting large amounts of data, cursor-based pagination is recommended. Paginated results are returned immediately for synchornous requests and is the preferred method for retrieving breakdowns.

Limitations

• Dates always refer to PDT unless specifed otherwise
• Revenue metrics may not be available if the number of impressions is too small
  • If the data for is not available with a specific breakdown, we recommend querying the total for the time period
• User access tokens generated in Monetization Manager or Business Manager cannot be used

Updates for Aggregation

Daily Impressions and Revenue

Query impressions and revenue for the placement on 1-4 May 2022 with a daily breakdown.

What might change: You may see that some data is unavailable following the change.

The revenue and CPM data points that are not available due to insufficient number of impressions will not be included in the results field in the API response. Instead, the corresponding entries will be added to the omitted_results field. They will include the time, metric and breakdowns fields, but they will not include the value - please refer to the sample response at the bottom of this page.

Request Syntax

Use the GET ID > adnetworkanalytics endpoint to get audience network insights for a business, property, or app.

GET /<ID>/adnetworkanalytics

Example GET Request

To get insights, send a GET request to the /<ID>/adnetworkanalytics endpoint with a comma-separated list of metrics and optional comma-separated list of breakdowns where <ID> is your Meta business ID, property ID, or app ID. The following example gets metrics over a single 24 hour period and limiting the results to 2 responses per metric.

      curl -X GET https://graph.facebook.com/v21.0/BUSINESS_ID/adnetworkanalytics
      ?metrics=["fb_ad_network_request","fb_ad_network_imp","fb_ad_network_click","fb_ad_network_revenue"]
      &breakdowns=["placement","country"]
      &since=2021-08-06
      &until=2021-08-06
      &limit=2
      

Example Response

{
  "data": [
    {
      "query_id": "531234567890123456789012345683d6",
      "results": [
        {
          "time": "2021-08-06T07:00:00+0000",
          "metric": "fb_ad_network_imp",
          "breakdowns": [
            {
              "key": "placement",
              "value": "123456789012345"
            },
            {
              "key": "country",
              "value": "AE"
            }
          ],
          "value": "1200"
        },
        {
          "time": "2021-08-06T07:00:00+0000",
          "metric": "fb_ad_network_imp",
          "breakdowns": [
            {
              "key": "placement",
              "value": "123456789012345"
            },
            {
              "key": "country",
              "value": "AU"
            }
          ],
          "value": "35"
        },
        {
          "time": "2021-08-06T07:00:00+0000",
          "metric": "fb_ad_network_revenue",
          "breakdowns": [
            {
              "key": "placement",
              "value": "123456789012345"
            },
            {
              "key": "country",
              "value": "AE"
            }
          ],
          "value": "21.212345"
        },
        {
          "time": "2021-08-06T07:00:00+0000",
          "metric": "fb_ad_network_request",
          "breakdowns": [
            {
              "key": "placement",
              "value": "123456789012345"
            },
            {
              "key": "country",
              "value": "AD"
            }
          ],
          "value": "1"
        },
        {
          "time": "2021-08-06T07:00:00+0000",
          "metric": "fb_ad_network_request",
          "breakdowns": [
            {
              "key": "placement",
              "value": "123456789012345"
            },
            {
              "key": "country",
              "value": "AE"
            }
          ],
          "value": "12"
        },
        {
          "time": "2021-08-06T07:00:00+0000",
          "metric": "fb_ad_network_click",
          "breakdowns": [
            {
              "key": "placement",
              "value": "123456789012345"
            },
            {
              "key": "country",
              "value": "AE"
            }
          ],
          "value": "1"
        },
        {
          "time": "2021-08-06T07:00:00+0000",
          "metric": "fb_ad_network_click",
          "breakdowns": [
            {
              "key": "placement",
              "value": "123456789012345"
            },
            {
              "key": "country",
              "value": "CA"
            }
          ],
          "value": "2"
        }
      ],
      "omitted_results": [
        {
          "time": "2021-08-06T07:00:00+0000",
          "metric": "fb_ad_network_revenue",
          "breakdowns": [
            {
              "key": "placement",
              "value": "123456789012345"
            },
            {
              "key": "country",
              "value": "AU"
            }
          ]
        }
      ]
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    },
    "next": "https://graph.facebook.com/v10.0/142440604406900/adnetworkanalytics?access_token=<ACCESS_TOKEN>&since=2021-08-06&until=2021-08-06&breakdowns=%5B%22placement%22%2C%22country%22%5D&limit=2&metrics=%5B%22fb_ad_network_request%22%2C%22fb_ad_network_imp%22%2C%22fb_ad_network_click%22%2C%22fb_ad_network_revenue%22%5D&after=MQZDZD"
  }
}

Reference

Query Parameters

Available Metrics

Troubleshooting

Access Token Debugger

Use the Access Token Debugger to get detailed information for an access token, including permissions, validity, property access, and App ID associated with the token.

Error Messages