Insights API

Provides a single, consistent interface to retrieve ad statistics.

iOS 14.5 Updates

In response to Apple’s new policy, we are announcing breaking changes that will affect Attribution Windows.

To learn more about how Apple’s iOS 14.5 requirements will impact Facebook advertising, visit our Business Help Center aricles and our changelog:

Quickstart

Access for reporting and analytics. If you only use the Ad Insights API, you need the ads_read permission.

1. Marketing API Quickstart

2. Example Query: Campaign Statistics


1. Create App

Start by creating an app with the Marketing API Quickstart which generates sample code.You can start getting insights from your Facebook Pixel or App Ads SDKs by clicking the Create Ad reports below.

Marketing API Quickstart

2. Campaign Statistics

To get the statistics of a campaign's last 7 day performance:

use FacebookAds\Object\AdCampaign;
use FacebookAds\Object\Values\InsightsPresets;

$campaign = new AdCampaign('<AD_CAMPAIGN_ID>');
$params = array(
  'date_preset' => InsightsPresets::LAST_7_DAYS,
);
$insights = $campaign->getInsights(null, $params);
print_r($insights);
from facebook_business.objects import AdCampaign
campaign = AdCampaign('<AD_CAMPAIGN_ID>')
params = {
    'date_preset': AdCampaign.Preset.last_7_days,
}
insights = campaign.get_insights(params=params)
print insights
curl -G \
-d "date_preset=last_7d" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_CAMPAIGN_ID>/insights"

To learn more, see the Ad Insights, Reference.

Making Calls

The Insights API is available as an edge on any ads object.

API Method

act_<AD_ACCOUNT_ID>/insights

<CAMPAIGN_ID>/insights

<ADSET_ID>/insights

<AD_ID>/insights

You can request specific fields with a comma-separated list in the fields parameters:

curl -G \
-d "fields=impressions" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_OBJECT_ID>/insights"


Levels

Aggregate results at a defined object level. This automatically deduplicates data. For example, get a campaign's insights on ad level.

curl -G \
-d "level=ad" \
-d "fields=impressions,ad_id" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<CAMPAIGN_ID>/insights"


If you don't have access to all ad objects at the requested level, the insights call returns no data. For example, while requesting insights with level as ad, if you don't have access to one or more ad objects under the ad account, this api call will return a permission error.

Attribution Windows

Updates for iOS 14+

  • When action_attribution_windows is not set, the default attribution value is 7d_click. Once enforcement begins, 28 day views and clicks will no longer available and will return empty data.
  • For inactive legacy ads that have a 28 day window value, we will return this data.
  • For default or account level windows, the value will be set to 7 day after enforcement.
  • For queries using action_attribution_windows with 28 day values an empty data set will be returned.
    • Offline conversion metrics are not impacted by signal loss and will not be affected. 28 day data will still be returned.
  • The use_account_attribution_setting field is deprecated. We will instead switch such requests to the action_attribution_windows default of 7d_click.

Please visit our Breaking Changes changelog for more information on changes due to iOS 14.

The conversion attribution window provides timeframes that define when we attribute an event to an ad on Facebook. For background information, see Facebook Ads Help Center, How Attribution Reporting Works. We measure the actions that occur when a conversion event occurs and look back in time 1-day and 7-days. To view actions attributed to different attribution windows, make a request to /{ad-account-id}/insights. If you do not provide action_attribution_windows we use 7d_click and provide it under value.

For example specify action_attribution_windows and 'value' is fixed at 7d_click attribution window. Make a request to act_10151816772662695/insights?action_attribution_windows=['1d_click','1d_view'] and get this result:

"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608,
"1d_view": 86,
"1d_click": 6510
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344,
"1d_view": 27.354069767442,
"1d_click": 0.36135944700461
},

// if attribution window is _not_ specified in query. And note that the number under 'value' key is the same even if attribution window is specified.
// act_10151816772662695/insights
"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344
},

Field Expansion

Request fields at the node level and by fields specified in field expansion:

curl -G \
-d "fields=insights{impressions}" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_ID>"

Sorting

Sort results by providing the sort parameter with {fieldname}_descending or {fieldname}_ascending:

curl -G \
-d "sort=reach_descending" \
-d "level=ad" \
-d "fields=reach" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<ADSET_ID>/insights"

Ads Labels

Stats for all labels whose names are identical. Aggregated into a single value at an ad object level. See Ads Labels, Reference.

curl -G \  
-d "fields=id,name,insights{unique_clicks,cpm,total_actions}" \
-d "level=ad" \
-d 'filtering=[{"field":"ad.adlabels","operator":"ANY", "value":["Label Name"]}]'  \
-d 'time_range={"since":"2015-03-01","until":"2015-03-31"}' \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_OBJECT_ID>/insights"

Clicks Definition

To better understand the three click metrics that Facebook offers today, please read the definitions and usage of each below:

  • Link Clicks, actions:link_click - The number of clicks on ad links to select destinations or experiences, on or off Facebook-owned properties. See Ads Help Center, Link Clicks

  • Clicks (All), clicks - The metric counts multiple types of clicks on your ad, including certain types of interactions with the ad container, links to other destinations, and links to expanded ad experiences. See Ads Help Center, Clicks(All)

Deleted and Archived Objects

Ad units may be DELETED or ARCHIVED. The stats of deleted or archived objects appear when you query their parents. This means if you query impressions at the ad set level, results include impressions from all ads in the set it, regardless of whether the the ads are in a deleted or archived state. See also, Storing and Retrieving Ad Objects Best Practice.

However if you query at a certain level, such as level=ad, objects that have been archived or deleted do not appear. As the result, the total stats of the parent node may be greater than the stats of its children.

By default, ARCHIVED objects are not included in the response of the insights edge, such as act_&lt;AD_ACCOUNT_id>/insights?level=ad.

You can get the stats of ARCHIVED objects from their parent nodes though, by providing an extra filtering parameter.

To get the stats of all ARCHIVED ads in an ad account listed one by one:

curl -G \
-d "level=ad" \
-d "filtering=[{'field':'ad.effective_status','operator':'IN','value':['ARCHIVED']}]" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/insights/"

Deleted Objects Insights

You can query insights on deleted objects if you have their IDs or by using the ad.effective_status filter. For example, if you have the ad set ID:

curl -G \
-d "fields=id,name,status,insights{impressions}" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<ADSET_ID>"

In this example, we query with ad.effective_status:

POST https://graph.facebook.com/<VERSION>/act_ID/insights?access_token=token&appsecret_proof=proof&fields=ad_id,impressions&date_preset=lifetime&level=ad&filtering=[{"field":"ad.effective_status","operator":"IN","value":["DELETED"]}]

Troubleshooting

Timeouts

The most common issues causing failure at this endpoint are too many requests and time outs:

  • On /GET or synchronous requests, you can get out-of-memory or timeout errors.
  • On /POST or asynchronous requests, you can possibly get timeout errors. For asynchronous requests, it can take up to an hour to complete a request including retry attempts. For example if you make a query that tries to fetch large volume of data for many ad level objects.

Recommendations

  • There is no explicit limit for when a query will fail. When it times out, try to break down the query into smaller queries by putting in filters like date range.
  • Unique metrics are time consuming to compute. Try to query unique metrics in a separate call to improve performance of non-unique metrics.

Rate Limiting

The Facebook Insights API utilizes rate limiting to ensure an optimal reporting experience for all of our partners. For more information and suggestions, see our Insights API Limits & Best Practices.

Related Resources

Any endpoints not in the above list are not covered in this API. If you plan to include reports from Facebook in your solution, see Facebook Platform Terms and Developer Policies for Marketing API.