Provides a single, consistent interface to retrieve ad statistics.
Before you can get data on your ad's performance, you should set up your ads to track the metrics you are interested in. For that, you can use URL Tags , Meta Pixel , and the Conversions API .
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 articles and our changelog:
GET /{ad-account-id}/insights
GET /{ad-id}/insights
GET /{ad-set-id}/insights
GET /{campaign-id}/insights
POST /{ad-account-id}/insights
POST /{ad-id}/insights
POST /{ad-set-id}/insights
POST /{campaign-id}/insights
You will need:
ads_read
permission.To get the statistics of a campaign's last 7 day performance:
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 .
The Insights API is available as an edge on any ads object.
API Method |
---|
|
|
|
|
You can request specific fields
with a comma-separated list in the fields
parameters. For example:
curl -G \
-d "fields=impressions" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/ v21.0
/AD_OBJECT_ID/insights"
{ "data": [ { "impressions": "2466376", "date_start": "2009-03-28", "date_stop": "2016-04-01" } ], "paging": { "cursors": { "before": "MAZDZD", "after": "MAZDZD" } } }
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/ v21.0
/CAMPAIGN_ID/insights"
{ "data": [ { "impressions": "9708", "ad_id": "6142546123068", "date_start": "2009-03-28", "date_stop": "2016-04-01" }, { "impressions": "18841", "ad_id": "6142546117828", "date_start": "2009-03-28", "date_stop": "2016-04-01" } ], "paging": { "cursors": { "before": "MAZDZD", "after": "MQZDZD" } } }
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
set to 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.
action_attribution_windows
is not set, the default attribution value is 7d_click
and 1d_view
. Once enforcement begins, 28 day views will no longer be available and will return empty data.use_account_attribution_setting
field is deprecated. We will instead switch such requests to the action_attribution_windows
default of 7d_click
and 1d_view
.Please visit our Breaking Changes changelog for more information on changes due to iOS 14.
The conversion attribution windowprovides timeframes that define when we attribute an event to an ad on a Meta app. For background information, see Meta Business Help Center, About attribution windows
. 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 },
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/ v21.0
/AD_ID"
{ "id": "6042542123268", "name": "My Website Clicks Ad", "insights": { "data": [ { "impressions": "9708", "date_start": "2016-03-06", "date_stop": "2016-04-01" } ], "paging": { "cursors": { "before": "MAZDZD", "after": "MAZDZD" } } } }
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/ v21.0
/AD_SET_ID/insights"
{ "data": [ { "reach": 10742, "date_start": "2009-03-28", "date_stop": "2016-04-01" }, { "reach": 5630, "date_start": "2009-03-28", "date_stop": "2016-04-03" }, { "reach": 3231, "date_start": "2009-03-28", "date_stop": "2016-04-02" }, { "reach": 936, "date_start": "2009-03-29", "date_stop": "2016-04-02" } ], "paging": { "cursors": { "before": "MAZDZD", "after": "MQZDZD" } } }
Stats for all labels whose names are identical. Aggregated into a single value at an ad object level. See the Ads Labels Reference for more information.
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/ v21.0
/AD_OBJECT_ID/insights"
{ "data": [ { "unique_clicks": 74, "cpm": 0.81081081081081, "total_actions": 49, "date_start": "2015-03-01", "date_stop": "2015-03-31", }, ], "paging": { "cursors": { "before": "MA==", "after": "MA==", } } }
To better understand the click metrics that Meta 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 Meta-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)
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 using filtering, status filtering will be applied by default to return only Active objects. As a result, the total stats of the parent node may be greater than the stats of its children.
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/ v21.0
/act_<AD_ACCOUNT_ID>/insights/"
Note that only archived objects are returned in this response.
{ "data": [ { "impressions": "1741", "date_start": "2016-03-11", "date_stop": "2016-03-12" } ], "paging": { "cursors": { "before": "MAZDZD", "after": "MAZDZD" } } }
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/ v21.0
/AD_SET_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"]}]
{ "id": "6042147342661", "name": "My Like Campaign", "status": "DELETED", "insights": { "data": [ { "impressions": "1741", "date_start": "2016-03-11", "date_stop": "2016-03-12" } ], "paging": { "cursors": { "before": "MAZDZD", "after": "MAZDZD" } } } }
The most common issues causing failure at this endpoint are too many requests and time outs:
/GET
or synchronous requests, you can get out-of-memory or timeout errors./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.The Meta 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 .
The default behavior of the API is different from the default behavior in Ads Manager. If you would like to observe the same behavior as in Ads Manager, please set the field use_account_attribution_setting
to true.
Any endpoints not in the above list are not covered in this API. If you plan to include reports from Meta in your solution, see Meta Platform Terms and Developer Policies for Marketing API .