Facebook Ads Ad Insights - Data API Endpoint

Ad Insights by ad object id, access token, breakdowns, date preset, filtering, fields, version and level.

Get bulk Ad Insights data from the Facebook Ads API | Official API: https://developers.facebook.com/docs/marketing-apis | 👥  Contributors: steve 🚩  Report

✏️ Inputs

Ad Object ID ad_object_id Required

ID of the Facebook Ad object:

  • Account: act_<AD_ACCOUNT_ID>
  • Campaign: <CAMPAIGN_ID>
  • Ad Set: <ADSET_ID>
  • Ad: <AD_ID>

See more under “Making Calls” here.

You can also get this ID from the URL in FB Ads Manager, e.g. https://business.facebook.com/adsmanager/manage/adsets?act=12345 will let you know your account ID is 12345 and you can then enter act_12345 for this value.

Access Token access_token Required

Your access token for the Marketing API: https://developers.facebook.com/apps/

You’ll need to then go under Products > Marketing API > Tools (left hand column) and generate a token with ads_read and read_insights permissions.

Breakdowns breakdowns Optional

How to break down action results. Supports more than one breakdowns.

See more here: https://developers.facebook.com/docs/marketing-api/insights/parameters/v7.0#parameters-and-fields

Date Preset date_preset Optional

Date to fetch data back from: today, yesterday, this_month, last_month, this_quarter, maximum, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year

E.g. maximum
Filtering filtering Optional

Filtering options, see more under: https://developers.facebook.com/docs/marketing-api/insights

E.g. an example might be [{"field":"ad.adlabels","operator":"ANY", "value":["Label Name"]}]

E.g. [{"field":"ad.adlabels","operator":"ANY", "value":["Label Name"]}]
Fields fields Default account_id,ad_id,adset_id,campaign_id,date_start,date_stop,impressions,spend,ad_name,adset_name,campaign_name

Fields to get back, separated by commas. See the full list of available fields. Popular fields:

  • account_id
  • ad_id
  • adset_id
  • campaign_id
  • date_start
  • date_stop
  • impressions
  • spend

  • ad_name

  • adset_name
  • campaign_name

  • canvas_avg_view_percent

  • canvas_avg_view_time
  • clicks
  • conversion_values
  • conversions
  • cost_per_action_type
  • cost_per_conversion
  • cpc
  • cpm
  • ctr
  • estimated_ad_recall_rate
  • estimated_ad_recallers
  • frequency
  • full_view_impressions
  • full_view_reach
  • purchase_roas
  • website_ctr
  • website_purchase_roas

If you want to better understand a particular ad or ad set, try using actions here.

Version version Default 13.0

Facebook Ads API Version. E.g. if you need to use an older version, provide the value 9.0.

Level level Optional

Level of aggreagtion

📝 Notes

Posted by steve on June 29, 2022, 6:31 a.m. 🚩  Report

⚡️ Endpoint

GET https://graph.facebook.com/v{{version}}/{{ad_object_id}}/insights?access_token={{ access_token }}&fields={{ fields }}&level={{ level }}&breakdowns={{ breakdowns }}&date_preset={{ date_preset }}&filtering={{ filtering }}