Marketing API Version

Insights

This insights edge provides a single, consistent interface to retrieve an ad's statistics.

  • Parameters - Parameters available on this endpoint.
  • Fields - Options for in the fields parameter for this endpoint.
  • Breakdowns - Group results from API calls
  • Action Breakdowns - Understanding the response from action breakdowns.
  • Async Jobs - For requests with large results, use asynchronous jobs
  • Limits and Best Practices - Explains Insights API call limits, filtering and best practices.

Making A Call

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"

Attribution Windows

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, 7-days, and 28 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 28d_click and 1d_view and provide it under 'value'.

For example specify action_attribution_windows and 'value' is fixed at 28d_click and 1d_view attribution windows. 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:

  1. Inline Link Clicks, inline_link_clicks - This metric is defined as the number of clicks on links to select destinations or experiences, on or off Facebook-owned properties. The Inline Link Clicks metric uses a fixed 1-day clickthrough attribution window (1d_click) from Link Click actions (actions:link_click). Inline Link Clicks continues to be the metric used for click optimization and CPA billing. The metric includes link clicks that may lead to:

    • Websites
    • App stores or app deep links
    • Click to call
    • Click to message
    • Maps/directions app
    • Facebook Canvas
    • Facebook lead forms
    • Facebook Marketplace
    • Videos hosted by another website (including videos embedded in News Feed ads but hosted on a video platform such as YouTube or Vimeo)
  2. Link Clicks, actions:link_click - This metric has the same definition as Inline Link Clicks, however it returns results based on the attribution window, action_attribution_windows, setting in your query. By default it is set to a 28-day click, 1-day view or 28d_click and 1d_view attribution window by default.

  3. Clicks (All), clicks - This metric has the same definition as Inline Link Clicks, however it returns results based on action_attribution_windows, setting in your query. By default it is set to a 28d_click and 1d_view attribution window.

Deleted and Archived Objects

Ad units may be DELETED or ARCHIVED. The stats of deleted or archived objects are represented when querying their parents (e.g. querying impressions at the ad set level will include impressions from all ads within it, regardless of deleted or archived state).

However if you query the report by a certain level, such as level=ad, objects that have been archived or deleted will not be represented. 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_<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.

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

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.